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Introduction 



1 Introduction 

This document describes the system interfaces for compiled application programs that will 
run on operating systems built on the IBM Microkernel technology for the PowerPC 
Architecture. 

This document includes by reference other generally available documents as necessary. The 
reader may find the following documents of interest: 

• The PowerPC Architecture: A Specification for A New Family of RISC Processors, 
Second Edition, IBM Corporation (ISBN 1-55860-316-6) 

• PowerPC Microprocessor Family: The Programming Environments, IBM/Motorola (IBM 
order number MPRPPCFPE-01 or Motorola order number MPCFPE/AD) 

• PowerPC 603 RISC Microprocessor User's Manual, IBM/Motorola (IBM order number 
MPR603UMU-01 or Motorola order number MPC603UM/AD) 

• Executable and Linking Format (ELF), Tool Interface Standards Committee (Review 
Draft Version 1.1a) 

• Tool Interface Standards Portable Formats Specification, Tool Interface Standards 
Committee (Version 1.0) 

• System V Application Binary Interface, Third Edition, UNIX System Laboratories (ISBN 0- 
13-100439-5) 

• System V Application Binary Interface, PowerPC Processor Supplement, Sun 
Microsystems (Draft dated March, 1995) 

Where possible, this ABI has maintained compatibility with System V Application Binary 
Interface, PowerPC Processor Supplement. Incompatibilities are noted in the document 
by "System V ABI Note" comments. 

• SOMObjects Developer Toolkit Programmer's Reference Manual, IBM Corporation 
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1.1 Revision Control 

This material was compiled from a variety of sources and was edited by BJ Hargrave, IBM 
Personal Software Products. Comments can by sent to hargrave@austin.ibm.com. 

All changes from the previous draft are marked with revision bars. 

1 . Release 1 (December 8, 1 995 7:31 pm) 
This is the first Release of this document. 
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2 Instruction Set 

The PowerPC Architecture is defined in PowerPC Architecture, IBM Corporation. PowerPC 
Architecture describes both the 32-bit and 64-bit portions of the architecture. This ABI 
document only defines a 32-bit ABI for PowerPC-based operating systems. Also see 
PowerPC Microprocessor Family: The Programming Environments, IBM/Motorola, for details 
on a 32-bit implementation of the PowerPC Architecture. 

ABI conforming programs containing machine instructions must use the 32-bit PowerPC 
instruction set including the instruction encodings and semantics as defined by the 
architecture. 

A processor must implement the instruction set of the architecture, perform the operations 
indicated by the instructions and produce the expected results. No performance constraints 
are levied by the ABI. A software emulation of the processor architecture could be ABI 
conforming. 

Note: The use of PowerPC 601 instructions which are not part of the PowerPC Architecture 
is not ABI conforming. Programs using these instructions will function on the 
PowerPC 601 but will not on other PowerPC implementations. 



Release 1 



3 



OS/2 Application Binary Interface for PowerPC (32-bit) 



2.1 Restricted Instructions 

An ABI conforming processor may implement the optional instructions from the PowerPC 
Architecture as well as instructions not in the architecture. However, programs that use these 
instructions will not be ABI conforming. 

All instructions that are neither privileged nor optional can be assumed to exist and function 
properly and may be used by ABI conforming programs. However, the following instructions 
that handle non-scalar data are not ABI conforming and may not be used by ABI conforming 
programs. 



Table 2-1 : Load/Store String Instructions 



Mnemonic 


Description 


lswi 


load string word immediate 


lswx 


load string word indexed 


stswi 


store string word immediate 


stswx 


store string word indexed 


Table 2-2: Load/Store Multiple Instructions 


Mnemonic 


Description 


lmw 


load multiple word 


stmw 


store multiple word 



These instructions all generate alignment exceptions when executed in the Little Endian 
mode of the processor. 
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3 Data Representation 

The PowerPC Architecture supports the following operand sizes: 

Table 3-1 : Operand types and sizes 



Operand 


Length 


Addr 28:31 if aligned 


Byte 


8 bits 


bbbb 


Halfword 


1 6 bits 


bbbO 


Word 


32 bits 


bbOQ 


Doubleword 


64 bits 


bOOO 


Quadword 


1 28 bits 


0000 



Note: An "b" indicates that the bit position can contain either 0 or 1 . 

Note: Although not permitted as storage operands by the PowerPC Architecture, quadwords 
are shown to demonstrate alignment and size. 
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3.1 Byte Ordering 

Byte ordering defines how the bytes that make up the larger, multi-byte operands are 
ordered in memory. Big Endian ordering means that the most significant byte (msb) is 
located in the lowest addressed byte position in the operand (byte 0). Little Endian ordering 
means that the least significant byte (Isb) is located in the lowest addressed byte position in 
the operand (byte 0). 

The PowerPC Architecture supports both Big Endian or Little Endian byte ordering. This 
document defines an ABI based upon the Little Endian byte ordering. 

The following figures illustrate the bit and byte numbering within the various size operands. 
Little Endian byte numbers are in the upper right and Big Endian byte numbers are in the 
upper left. Bit numbers appear in the lower corners. 

Figure 3-1 : Halfword 
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Figure 3-2: Word 
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Figure 3-3: Doubleword 
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Figure 3-4: Quadword 
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3.2 Scalar Types - Size and Alignment 

This section describes the mapping of C/C++ scalar data types onto the PowerPC 
Architecture.The Size column indicates the size of the data type in bytes. The Alignment 
column indicates the preferred alignment for the data type. If the data type is not aligned to 
the preferred alignment then alignment exceptions may occur when accessing the data from 
memory. Scalar data types on the PowerPC are aligned on their "natural" boundaries. That 
is, their preferred alignment is equal to their size. 

3.2.1 8-bit Integer 



Table 3-2: 8-bit Integer 



Operand 


C/C++ type 


Size 


Alignment 


signed byte 


signed char 


1 


1 


unsigned byte 


char 


1 


1 




unsigned char 







3.2.2 16-bit Integer 



Table 3-3: 16-bit Integer 



Operand 


C/C++ type 


Size 


Alignment 


signed halfword 


short 

signed short 


2 


2 


unsigned halfword 


unsigned short 
wchar t 
UniChar 


2 


2 



Note: unichar is the data type representing Unicode characters. 
3.2.3 32-bit Integer 



Table 3-4: 32-bit Integer 



Operand 


C/C++ type 


Size 


Alignment 


signed word 


int 

signed int 
long 

signed long 


4 


4 


unsigned word 


unsigned int 
unsigned long 


4 


4 



Note: The type of an enumeration data type, e.g. the C/C++ type enum, is the smallest 
integral type that can contain all of the enumeration values. 
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3.2.4 64-bit Integer 



Table 3-5: 64-bit Integer 



Operand 


C/C++ type 


Size 


Alignment 


signed doubleword 


__int64 
long long 
signed long long 


8 


8 


unsigned doubleword 


uint64 
unsigned long long 


8 


8 



Note: Support for 64-bit integers is currently implemented by some 32-bit compilers as 
long long although this data type is not part of the current ANSI C specification. 



System V ABI Note: The System V Application Binary Interface, PowerPC Processor 
Supplement defines 64-bit integers (long long) and their semantics, but specifically 
indicates that their use is non-conforming. 64-bit integers are part of this ABI and their 
use is conforming. The definition and semantics are the same in both ABIs. 



3.2.5 Pointer 



Table 3-6: Pointer 



Operand 


C/C++ type 


Size 


Alignment 


unsigned word 


any- type * 
any- type (*) () 


4 


4 



Note: This is a 32-bit ABI, therefore pointers are 32-bits in size. 
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OS/2 Application Binary Interface for PowerPC (32-bit) 
3.2.6 Single Precision Floating Point 



Table 3-7: Single Precision Floating Point 



Operand 


C/C++ type 


Size 


Alignment 


word, single precision 
(IEEE 754) 


float 


4 


4 



3.2.7 Double Precision Floating Point 



Table 3-8: Double Precision Floating Point 



Operand 


C/C++ type 


Size 


Alignment 


doubleword, double 
precision (IEEE 754) 


double 


8 


8 



3.2.8 Extended Precision Floating Point 

Table 3-9: Extended Precision Floating Point 



Operand 


C/C++ type 


Size 


Alignment 


quadword, extended 


long double 


16 


1 6 (for 


precision (ordered 






structures, 


pair of double 






only 8 byte 


precision floating 






alignment is 


point values) 






required 








otherwise) 



The extended precision floating point format is an ordered pair of double precision 
values. Together they represent the number which is their algebraic sum. The "higher- 
order" double precision value is larger in magnitude and is stored in the lower-addressed 
doubleword of the quadword. The "lower-order" double precision value is smaller in 
magnitude and is stored in the higher-addressed doubleword of the quadword. The two 
double precision values are defined and manipulated such that the lower-order double 
precision value "extends" the precision of the higher-order double precision value. 

• The lower-order value typically has an exponent which is 53 less than that of the 
higher-order value, but this is not mandated. 

• The signs of the two double precision values may differ. 

• The exponent range is no greater than double precision. 

• As the absolute value of the extended precision quantity becomes very small, the 
additional precision provided by the lower-order double precision value decreases, 
until for denormalized numbers, the precision is the same as double precision. 
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The extended precision floating point format need not be conformant with IEEE 754. The 
following deviations are permitted. 

• The only rounding mode that must be supported in round-to-nearest. 

• The IEEE special numbers NaN and INF may not be fully supported. Even basic 
operations such as addition and subtraction may not propagate NaN and INF 
correctly. 

• The IEEE status flags in fpscr for overflow, underflow, etc. may not be correctly set, 
even by basic operations such as addition and subtraction. 



System V ABI Note: The System V Application Binary Interface, PowerPC Processor 
Supplement defines extended precision floating point (long double) differently. It is 
defined there as a 128-bit IEEE 754 conforming datatype with a sign bit, a 15 bit 
exponent with a bias of -16383, and a 11 2 bit fraction with a leading implicit bit. It is 
treated as a structure for the purposes of parameter passing and return values. 
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3.3 Aggregates and Unions - Alignment and Padding 

Aggregates (structures and arrays) and unions are aligned using the alignment of the most 
strictly aligned component, i.e. the component with the largest alignment dictates the 
alignment of the aggregate or union in which it is contained. Each component is assigned the 
lowest available offset with the appropriate alignment. This may require internal padding, 
depending on the size of the previous component. The size of on aggregate or union is 
always a multiple of its alignment. Thus a structure or union may require "tail" padding to 
meet size and alignment constraints. 

The following figures illustrate structure and union member alignment and packing for Little 
Endian byte ordering. Little Endian byte numbers are in the upper right. 

Figure 3-5: Small Structure 



struct 
{ 

char c ; 

}; 

Byte aligned, sizeof is 1 . 






0 

c 







Figure 3-6: Structure with No Padding 




Word aligned, sizeof is 8 
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Figure 3-7: Structure with Padding 



struct 
{ 

char c; 
double d; 
short s ; 

}; 

Doubleword aligned, sizeof is 24. 
The structure is padded both 
internally, to maintain proper 
alignment of the members, and at the 
"tail" to maintain proper size of the 
structure. 
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Figure 3-8: Structure with Packing on 1 Byte Boundary 



struct 
{ 



}; 



char c; 
double d; 
short s ; 
1 ong n ; 



Byte aligned, sizeof is 15. The 
structure is not padded either 
internally or at the "tail". Both the 
structure itself and its members are 
improperly aligned for direct access. 
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Figure 3-9: Union Allocation 



union 
{ 

char c ; 
short s ; 
int j ; 

}; 

Word aligned, sizeof is 4. 
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3.4 Unaligned Data Access 

Since PowerPC processors do not support unaligned data access in Little Endian mode 
without causing an alignment exception, compiler assistance is necessary to support existing 
code with poorly aligned data structures. Many legacy applications are from the Intel x86 
which is very forgiving of unaligned data. Unaligned data accesses on the Intel x86 chips are 
penalized only cycles rather than the expensive alignment exceptions of the Little Endian 
mode of the PowerPC. 



One of the key areas of legacy applications is OS/2, an operating system that originated on 
the Intel x86 architecture. In fact there are numerous system data structures that are not 
"naturally" aligned. For this reason, compiler support is critical to facilitate the porting of 
applications to OS/2 for the PowerPC and the sharing of persistent data between both 
platforms. While this compiler support is not required to produce ABI-compliant code, it is 
highly recommended. In short, the compiler support involves using multiple instructions to 
access an unaligned scalar quantity without causing an alignment exception. For example, in 
Figure 3-8, "Structure with Packing on 1 Byte Boundary", on page 13, member n in the 
structure is improperly aligned. Assuming that r3 points to the structure and the structure is 
aligned on a word boundary, the following code example would load the value of n into r4 
without causing an alignment exception. 



lwz %r4 , 12 (%r3) 

lbz %r5,ll(%r3) 

slwi %r4,%r4,8 

or %r4 , %r4 , %r5 



load bytes 1,2,3 into r4 

load byte 4 into r5 

shift bytes 1,2,3 left one byte 

or all bytes together in r4 



Similar techniques can be used to access and update scalars with other misalignments. All 
multi-byte scalar data types listed in § 3.2, "Scalar Types - Size and Alignment", should be 
handled. The specific techniques are left to the compiler vendor. 



The compiler can ensure that all automatic and global data are "naturally" aligned. The 
compiler can then determine, at compile time, the specific alignment problems of individual 
members of an aggregate and generate the appropriate code to avoid alignment exceptions 
when these members are accessed. 



When dealing with pointers, however, the alignment of the data referenced by the pointer is 
unknown at compile time. Therefore one of the following choices must be made. 

1 . Code is generated to assemble the data item by accessing only individual bytes. This 
choice makes no assumptions about the alignment of the data. 

2. Code is generated to determine at runtime if the data item being accessed is "naturally" 
aligned. If the data item is aligned it can be directly accessed. Otherwise it accessed by 
individual bytes 

3. Code is generated accessing the data item assuming it is naturally aligned. If the data 
item is unaligned, an alignment exception will be generated and the alignment exception 
handler will be invoked. The exception handler will then complete the instruction, 
accessing the data item by individual bytes, and return control to the next instruction. 
This choice assumes that most pointers will point to naturally aligned data items. 

It is recommended that compiler support for unaligned data access be activated by either 
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1 . The use of a structure packing pragma which causes a structure to have members which 
are not "naturally" aligned or to have the structure's size not be a multiple of the "natural" 
alignment of the structure. 

2. The use of a new pragma that signifies that a structure may contain unaligned members 
or a pointer variable may point to unaligned data. 
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3.5 Bit Fields 

Structure and unions may have bit fields which define integral objects with a specified 
number of bits. 



Table 3-10: Bit Field Ranges 



Bit field type 


Width (w) 


Range 


signed char 
char 

unsigned char 


1 to 8 bits 


_ 2 w1 tQ 2 w1_., 

0 to 2 W -1 
0 to 2 W -1 


signed short 
short 

unsigned short 


1 to 16 bits 


_ 2 w1 tQ 2 w1. 1 

0 to 2 W -1 
0 to 2 W -1 


signed int 
int 

unsigned int 
enum 


1 to 32 bits 


_ 2 w1 tQ 2 w1. 1 

0 to 2 W -1 
0 to 2 W -1 
0 to 2 W -1 


signed long 
long 

unsigned long 


1 to 32 bits 


_ 2 w1 tQ 2 w1. 1 

0 to 2 W -1 
0 to 2 W -1 



Bit fields that are not specified as either signed or unsigned always have non-negative 
values. Bit fields are subject to the same rules of size and alignment as their declared type in 
addition to the following. 

• Bit fields are allocated within a storage unit from least significant bit to most significant bit. 

• Bit fields do not cross the boundaries of its declared type. That is, a bit field cannot span 
between multiple storage units of its declared type. 

• Bit fields must share a storage unit with other members (either bit field or non-bit field), if 
and only if there is sufficient space within the storage unit of its declared type. 

• The declared type of an unnamed bit field does not affect the alignment of a structure or 
union. However, they do cause alignment from the beginning of the structure based upon 
their declared type. An unnamed bit field of zero-width prevents any further member 
(either bit field or non-bit field) from residing in the storage unit of the declared type of 
the zero-width bit field. 
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The following figures illustrate structure and union member offsets for Little Endian byte 
ordering. Little Endian byte numbers are in the upper right. Bit numbers appear in the lower 
corners. 



Figure 3-10: Bit Field Right-to-Left Allocation 



struct 
{ 

int j : 5 
int k : 6 
int m : 7 

}; 

Word aligned, sizeof is 4. The 
structure is "tail" padded so that the 
size of the structure is a multiple of its 
alignment. 
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Figure 3-11 : Bit Field Boundary Alignment 



struct 
{ 

short s : 9 ; 
int j : 9 ; 
char c ; 
short t : 9 ; 
short u : 9 ; 
char d ; 

}; 

Word aligned, sizeof is 12. 
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Figure 3-12: Bit Field Storage Unit Sharing 



struct 
{ 

char c ; 
short s : 8 ; 

}; 

Halfword aligned, sizeof is 2. 
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Figure 3-13: Unnamed Bit Fields 



struct 
{ 

char c ; 
int : 0 
char d ; 
short : 9 ; 
char e ; 

}; 

Byte aligned, sizeof is 9. The 
declared types of the unnamed bit 
fields do not affect the alignment of 
the structure. 
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As can be seen in the above figures, bit fields of the largest integral types (int or long) 
pack more densely than bit fields of smaller types. The smaller types can be used to force a 
particular alignment. 
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3.6 UTF-8 

UTF-8 is a transformation of Unicode characters such that there are no embedded null bytes 
in a character string. This allows Unicode character strings to be encoded in a way that they 
may be used in places that historically only support single-byte character strings which may 
use the null-byte as a string terminator. UTF-8 encoded character strings are specified in 
several places in this ABI. 

The UTF-8 transformation encodes Unicode characters in the range o - Oxffff using multi- 
byte characters of 1 , 2 and 3 bytes in length. Single-byte characters are reserved for the 
ASCII characters in the range o - 0x7F. These characters all have the most significant bit 
set to zero. For all characters which are encoded using more than one byte, the number of 
bytes used is indicated by the number of most significant bits which are set to one. 
Subsequent bytes of the multi-byte character are all of the form ioxxxxxx. 



Table 3-11 : UTF-8 Transformation 



Bytes 


Bits 


Range 


Byte sequence in binary 


i 


7 


0x0000 - 0x007F 


0 wvwvv 


2 


11 


0x0080 - 0x07FF 


110 wwv 1 0 www 


3 


16 


0x0800 - OxFFFF 


1110 ww 1 0 www 1 0 www 



The Unicode character value is just the concatenation of the vbits in the multi-byte 
encoding. When there are multiple ways to encode a value, only the shortest encoding is 
legal. 
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4 Procedure Linkage Conventions 

This chapter defines the standard system function calling convention. It is applicable to both 
procedural and object-oriented function calls. All system interfaces require this calling 
convention. 

Note: The standard system function calling conventions apply only to global functions. Local 
functions that are not reachable from other compilation units may use other calling 
conventions. 
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4.1 Registers 

The PowerPC Architecture provides 32 General Purpose Registers (GPRs). Each GPR is a 
word (32-bit) in size and is used for integer and address computations. There are also 32 
Floating Point Registers (FPRs). Each FPR is a doubleword (64-bit) in size and is used for 
floating point computations. There are also other registers with specific purposes. All 
registers (GPR, FPR and other) are global to all functions in a thread of execution. 

This table gives a description of the usage of the PowerPC registers in this ABI. 



Table 4-1: Register Usage 



Register 


Status 


Usage 


rO 


Volatile" 1 " 


Language specific purpose. 


rl 


Dedicated 


Stack pointer. Always valid. 


r2 


Dedicated 


Reserved for system use. This register points to 
the Thread Information Block and should not be 
modified by application code. See § 11 .4, 

"ThfoaH Infnfm at inn R Inn If" nn nano 1 "^.A. fnr 

I I 1 1 CClU IIIIUIIIIcUIUII LJ I UUIa , Ul I UdLjC I Ot, I U I 

details. 


r3 
r4 


Volatile 


Parameter passing and return values. 


r5 
r6 
r7 


Volatile 


Parameter passing. 


r8 
r9 
rlO 






rll 
rl2 
rl3 


Volatile" 1 " 


Language specific purpose. 




System V ABI Note: The System V Application 
Binary Interface, PowerPC Processor 
Supplement defines ri3 to be a Small Data 
Area Pointer. 
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Table 4-1 : Register Usage (Continued) 



Register 


Status 


Usage 


rl4 


Non-volatile 


Local variables. 


rl5 






rl6 




Note: The stack frame layout assumes that a 


rl7 




contiguous set of GPRs will be allocated 


rl8 




from r3l down towards rl3. 


rl9 






r2 0 




Note: Programming languages that require a 


r21 




static scope pointer (e.g. Pascal) shall 


r22 




use r3i for that purpose. 


J_ Z Jj 






r24 






r25 






L Z, O 






TZ 1 












r29 






r30 






r31 






E U 


VUldlllc 


Ldiigudgc bpcoiiio purpobc. 


f 1 


Volatile 


Parameter passing and return values. 


f 9 






■F Q 

L J> 






L 4 






f 5 


Volatile 


Parameter passing. 


f 6 






f 7 






f 8 






f 9 


Volatile 


Language specific purpose. 


f 10 






f 11 






f 12 






f 13 
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Table 4-1 : Register Usage (Continued) 



Register 


Status 


Usage 


f 14 


Non-volatile 


Local variables. 


f 15 






f 16 




Note: The stack frame layout assumes that a 


f 17 




contiguous set of FPRs will be allocated 


f 18 




from f 31 down towards f 13. 


f 19 






f 20 






f21 






f 22 






f TO 
J_ _> 






f 24 






f25 






f 26 






f 27 






f 28 






f 29 






f 30 












CRO 


Volatile 


Condition Register fields. Each is 4 bits wide. 


CR1 




cr bit 6 (cri, floating point invalid operation 


LKb 




excepnonj is sei oy me caner ot a vanarjie 


CR6 




argument list function. See § 4.3.1 , "Variable 


CR7 




Argument Lists", on page 30 for more 






i nf ni*m at inn 

1 1 1 1 Ul I 1 I CU IUI I . 


f DO 


INUI 1 VVJldLIIC 


v-*Ui IUI LIUI 1 iicyibLcl llulUo. r_d.L<ll lo H- UlLo WlUfc;. 


CR3 




Together cro - CR7 make up the 32 bit cr 


CR4 




register. 


LR 


Volatile 


Link Register. Used to hold the address to which 






a railed function returns 


CTR 


Volatile" 1 " 


Count Register 


XER 


Volatile 


Fixed Point Exception Register 


FPSCR 


See Usage 


FPSCR 0:2 3 is volatile and fpscr 2 4 : 3i is global. 






fpscr 2 4;3i (the exception enable and rounding 






control bits) can be modified by routines that 






have such documented behavior. 



t The values in these volatile registers may be modified during the transfer of control 
from one function to another by system "glue" code. 



There are no special restrictions on the use of registers in system exception handling or 
signal routines. 
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4.2 Stack Frames 

In addition to the registers, each function can have a stack frame on the current thread's 
stack. Register rl is the stack pointer and points to the current stack frame. A function must 
acquire a stack frame if the function calls another function or requires any of the optional 
stack frame components. 

Figure 4-1 : Stack Frame Layout 



Stack 
pointer 



rl 



High Address 



Floating Point Register 
save area 



General Purpose Register 
save area 



cr save word 



local variable area 



parameter list area 



lr save word 



Back chain 



Low Address 



Stack Frame 
Header 



Table 4-2: Stack Frame Components 



Component 



Description 



Stack pointer, rl 



The stack pointer shall always maintain 16 byte alignment, shall 
always point to the first word of the lowest allocated, valid stack 
frame and shall grow down towards low addresses. Negative 
references from the stack pointer are not permitted. 

If a function requires a stack frame, the function's prologue shall 
atomically decrement the stack pointer and set the back chain 
pointer with one of the "Store Word with Update" instructions. 
Thus, the stack pointer always points to a linked list of stack 
frames. 

When releasing a stack frame, a function's epilogue shall 
atomically update the stack pointer prior to returning to the 
calling function by either setting it to the value of the back chain 
pointer or incrementing it by the same amount it was 
decremented in the function prologue. 
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Table 4-2: Stack Frame Components (Continued) 



Component 


Description 


Back chain 
pointer 


• The back chain pointer shall always point to the base of the 
previously allocated stack frame. Except for the first stack frame 
in the stack which has a back chain pointer of 0. 


lr save word 


• When a called function creates its stack frame, it shall save the 
value of lr when the function was entered into the lr save word 
of the callers stack frame. 

• When returning from a function, all non-volatile registers shall be 
restored prior to restoring lr. 


parameter list 
area 

(optional) 


• The parameter list area is a variable size area allocated by the 
caller. 

• It shall be large enough to contain the arguments the caller 
stores in it. 

• It is volatile and can be modified by the called function. 


local variable area 
(optional if stack 
frame padding is 
not required) 


• There is no restriction on the use and size of this stack frame 
component. 

• Any padding of the stack frame that is necessary to maintain 16 
byte alignment shall be in this stack frame component. 


cr save word 
(optional) 


• If a function modifies any of the non-volatile fields in cr, the non- 
volatile fields of cr, as they were at function entry, shall be 
saved. 


GPR save area 
(optional) 


• The size of the GPR save area shall be large enough to hold all 
the non-volatile GPRs from the lowest numbered non-volatile 
GPR used by the function to r3i inclusive. 

• Before a function modifies the value in a non-volatile GPR, rn, 

Lilt; VdlUt; Ul LIl, do IL vvdo dL IUIIULIUII cllLly, olldll Uc bdvcll III Lilt; 

word at offset 4*(n-31) from the address of the highest- 
addressed word of the GPR save area. Thus r3i is stored in the 
highest-addressed word, r3 0 in the next lower-addressed word, 
etc. 

Note: r3i may not participate in non-volatile GPR saving. See the 
description of the gpr3i nosave bit in Table 7-1 , "Function 
Tag Word," on page 58. 
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Table 4-2: Stack Frame Components (Continued) 



Component 


Description 


FPR save area 
(optional) 


• The size of the FPR save area shall be large enough to hold all 
the non-volatile FPRs from the lowest numbered non-volatile 
FPR used by the function to f 31 inclusive. 

• Before a function modifies the value in a non-volatile FPR, f n, 
the value of f n, as it was at function entry, shall be saved in the 
doubleword at offset 8*(n-31) from the address of the highest- 
addressed doubleword of the FPR save area. Thus f 31 is stored 
in the highest-addressed doubleword, f 3 0 in the next lower- 
addressed doubleword, etc. 



Except for the stack frame header (the back chain pointer and the lr save word) and any 
necessary padding to maintain the 1 6 byte alignment of the stack frame, no space need be 
allocated for stack frame components which are not used. If a function does not call any 
functions (a "leaf" function) and does not require any of the optional stack frame 
components, it need not establish its own stack frame. Any padding of the stack frame that is 
necessary to maintain 16 byte alignment shall be wholly within the local variable area. The 
parameter list area shall immediately follow the stack frame header. The register save areas 
(cr, gpr, fpr) shall contain no padding. 

See § 7.2, "Function Tags", on page 58 for information on function tags which describe the 
usage of the register save areas (lr, cr, gpr, fpr) of the stack frame. This information can 
be used by exception handlers to determine the contents of the non-volatile registers as they 
were when a function was entered. 

See § 7.3.1 , "Function Prologue and Epilogue", on page 63 for example code which 
demonstrates acquiring and releasing stack frames. 

See § 7.3.4, "Dynamic Stack Space Allocation", on page 74 for information on dynamically 
increasing the stack frame size once inside a function. 
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4.3 Parameter Passing 

For the PowerPC Architecture, it is more efficient to pass parameters in registers (GPRs and 
FPRs) rather than build parameter lists in memory (or on the stack). Since all computations 
are performed on registers and there are a large number of registers available, it makes 
sense to pass parameters in registers where they can be used immediately by the called 
function. The number of parameters that can be directly passed in registers is limited by the 
register usage definition in the ABI. 

Up to eight integer parameters, loaded sequentially in r3 through rio, and eight floating 
point parameters, loaded sequentially in f 1 through f 8, can be passed directly in registers. 
Only those parameter passing registers actually needed in a function call will be loaded with 
parameter values. The remaining unused parameter passing registers will contain undefined 
values. 

Only when a parameter cannot be passed in a register (more than eight integer or more than 
eight floating point parameters or the parameter is too large to be passed in a register) must 
the parameter list area component of the stack frame be allocated. The parameter list area 
need only be allocated large enough to contain only those parameters not being passed by 
register. The parameter list area is partitioned into parameter words with the first parameter 
word (0) being at the low address of the parameter list area immediately adjacent to the 
stack frame header. 

The following algorithm details how parameters are to be passed. For this algorithm, 
parameters are ordered from left (first parameter) to right and the evaluation order is 
unspecified. Let gr and f r be the number of the next available GPR and FPR, respectively 
and param be the address of the next available parameter word. Initialize gr to 3, f r to 1 
and param to the address of lowest-addressed word in the parameter list area. For each 
parameter, proceeding left to right, select its type from the following table and take the 
indicated action. 



Table 4-3: Parameter Passing Types and Actions 



Type 


Action 


* Single precision floating point 

* Double precision floating point 


If f r < 8, load the parameter value into FPR f r, 
set f r to f r+1 . 

Otherwise (no remaining parameter passing 
FPRs) treat as type Other. 


• Extended precision floating 
point 


If f r < 7, load the lower-addressed doubleword of 
the parameter value into FPR f r and the higher- 
addressed doubleword of the parameter value 
into FPR f r+1 . Set f r to f r+2. 
Otherwise (insufficient parameter passing FPRs) 
treat as type Other. 
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Table 4-3: Parameter Passing Types and Actions (Continued) 



Type 


Action 


• 8-bit, 16-bit or 32-bit integer 

• Pointer 

• Structure or union 

These shall be treated as a pointer 
to the object or to a copy of the 
object where necessary to enforce 
call-by-value semantics. The caller 
can pass a pointer to the object 
only if the callee treats the object 
as "constant". 


If gr < 1 0, load the parameter value into GPR gr, 
set gr to gr+1 . Parameter values smaller than 32 
bits in size are sign or zero extended as 
appropriate to 32 bits. 

Otherwise (no remaining parameter passing 
GPRs) treat as type Other. 


• 64-bit integer 


If gr < 9 and even, set gr to gr+1 . 
If gr < 9, load the lower-addressed word of the 
parameter value into GPR gr and the higher- 
addressed word of the parameter value into GPR 
gr+1 . Set gr to gr+2. 

Otherwise (insufficient parameter passing GPRs) 
treat as type Other. 


• Other 

Parameters not handled above are 
passed in the parameter list area 
of the callers stack frame. 


8-bit, 16-bit and 32-bit integer (sign or zero 
extended as appropriate to 32 bits) and pointer 
(including implicit pointers to structure or union) 
parameters are considered to have word size and 
alignment. Single precision floating point 
(converted to double precision floating point 
representation), double precision floating point 
and 64-bit integer parameters are considered to 
have doubleword size and alignment. Extended 

nrppiQinn flnptinn nnint narpmptprQ pcp 
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considered to have quadword size and 
doubleword alignment. 

Round param up to a multiple of the alignment 
required of the parameter and copy the 
parameter value byte-wise starting with the 
lowest addressed byte into bytes param[0] 

through param[size-1]. Set param to 
param+size. 



The values in registers and the bytes in the parameter list area which were skipped over by 
the actions above are undefined. 



Note: When passing single precision floating point values, either in an FPR or as a 

doubleword in the parameter list area, the value shall be rounded to single precision, 
if not already rounded to single precision, before being passed. 
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Figure 4-2: Parameter Passing Example 



typedef struct 
{ 

int a, b; 

double dd; 
} sparm; 
sparm s , t ; 
int c , d, e , f , g , 
long double Id; 
double ff, gg, hh, 



h; 



i i , j j , kk , 11, mm , nn ; 



func (c, ff, d, gg, e, hh, f, ii, 
nn) ; 



jj, h, Id, kk, 11, s, mm, t, 



General Purpose Registers 


Floating Point Registers 


Parameter List Area offsets 


r3 


c 


f l 


f f 


00 


11 (lo) 


r4 


d 


f2 


gg 


04 


11 (hi) 


r5 


e 


f 3 


hh 


08 


mm (lo) 


r6 


f 


f4 


ii 


OC 


mm (hi) 


r7 


g 


f 5 


j j 


10 


nn (lo) 


r8 


h 


f 6 


ld(lo) 


14 


nn (hi) 


r9 


ptr to s 


f 7 


Id (hi) 






riO: ptrtot 


f 8 


kk 







Note: (lo) and (hi) denote the lower-addressed and higher-addressed half of the 

parameter as stored in memory. The "ptr to" arguments are pointers to copies, if 
necessary, to preserve call-by-value semantics. 



4.3.1 Variable Argument Lists 

Functions should make no assumptions about the location of parameters that were passed 
to the function. Some otherwise portable functions assume that all arguments are passed on 
the stack and appear in increasing order on the stack. Functions with these assumptions 
have never been portable but have worked on many implementations. However, these 
functions will not work under this ABI as the majority of parameters are passed via register. 
Portable C and C++ programs should use <stdarg.h> to access parameters in variable 
argument lists. 



A caller of a function that takes a variable argument list (or an unprototyped function) shall 
set bit 6 of cr if it passes one or more parameters in floating point registers. It is strongly 
recommended that the caller clear the bit otherwise. Bit 6 of cr can be set with 

"creqv 6 , 6 , 6" and cleared with "crxor 6,6,6". 

The notification of parameters in FPRs by setting bit 6 in cr can be used by variable 
argument list functions in two ways. First, the variable argument list function can determine if 
it must store the parameter passing FPRs in memory. Second, by knowing that there are no 
floating point parameters, the function can avoid acquiring a "floating point state" for the 
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process. Having no "floating point state" means that the floating point registers need not be 
saved and restored on context switches. 

The cost of this notification is one additional non-memory reference instruction in all callers 
of variable argument list functions. ANSI C requires that all variable argument list functions 
be prototyped with a trailing ellipsis ("...")» but compiler vendors are expected to provide 
support for variable argument list functions in non-ANSI programs or to treat all non- 
prototyped functions as potentially having variable arguments. 

4.3.1.1 C Language Implementation 

The va_list type defined in <stdarg . h> shall have a storage representation as described 
below in Figure 4-3, "vajist Description". The source representation of the va_list type is 
not specified. 



Figure 4-3: va list Description 



struct va list 
{ 

char gpr; 

char fpr; 

char reserved [2] ; 

char * input arg area; 

char *reg save area; 

}; 


Member 


Description 


gpr 


Index into the array of 8 parameter passing GPRs, r3 through 
rio, stored in the register save area. Index 0 corresponds to 
r3, 1 to r4, etc. This is initialized by va start to contain the 
index of the first parameter passing GPR unused by 
parameters to the left of the ellipsis ("..."). If all parameter 
passing GPRs are used by parameters to the left of the 
ellipsis, then gpr shall be set to 8. 


fpr 


Index into the array of 8 parameter passing FPRs, f l through 
f 8, stored in the register save area. Index 0 corresponds to 
f l, 1 to f 2, etc. This is initialized by va start to contain the 
index of the first parameter passing FPR unused by 
parameters to the left of the ellipsis ("..."). If all parameter 
passing FPRs are used by parameters to the left of the ellipsis, 
then fpr shall be set to 8. 


reserved 


Padding. 


input arg area 


Location in the parameter list area of the stack frame which 
may have the next variable argument passed in memory. This 
is initialized by va start to contain the address of the first 
word in the parameter list area unused by parameters to the 
left of the ellipsis ("..."). 
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Figure 4-3: va list Description (Continued) 



reg_save_area 



Pointer to the register save area. This pointer is initialized by 
va_start to contain the address of the register save area. 
The register save area shall be doubleword aligned and large 
enough to store the parameter passing registers, r3 through 
rio and f 1 through f 8. The parameter passing registers are 
copied to the register save area during the function prologue. 
The registers are stored in the register save area beginning 
with r3 through rio optionally followed by f l through f 8 if cr 
bit 6 is set. 



The following suggests a possible implementation for variable argument list support but it is 
not included in the ABI specification. 

The va_start macro will require inline support from the compiler in order to properly 
initialize a va_list variable. The va_arg macro will require C runtime library support in 

order to manipulate the va_list variable. The runtime library can provide a va_arg 

function to be used by the va_arg macro. The va_arg function would return a pointer to 

the next argument of the specified type and would be defined as follows. 

void * va_arg ( va_list *argp, _va_arg_type type ) ; 

Compiler support would be necessary to convert the type specified to the va_arg macro to 
one of the values of the _var_arg_type type. 

Figure 4-4: va arg type Description 



typedef enum 
{ 

arg_ARGPOINTER , 
arg WORD, 
arg_DOUBLEWORD , 
arg REAL, 
arg_DOUBLEREAL 
} va arg type ; 


Value 


Description 


arg_ARGPOINTER 


The argument is a word in size and is passed in a parameter 
passing GPR, r3 through rio, or in memory. The argument is 
treated as a pointer to the actual argument (struct or union). 


arg WORD 


The argument is a word in size and is passed in a parameter 
passing GPR, r3 through rio, or in memory. The argument is 
an 8-bit, 1 6-bit or 32-bit integer or pointer (sign or zero 
extended as appropriate if necessary.) 


arg_DOUBLEWORD 


The argument is a doubleword in size and is passed in an odd/ 
even pair of parameter passing GPRs, r3 through rio, or in 
memory. The argument is a 64-bit integer. 
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Figure 4-4: va arg type Description (Continued) 



arg REAL 


The argument is a doubleword in size and is passed in a 
parameter passing FPR, f l through f 8, or in memory. The 
argument is a single precision floating point (converted to 
double precision floating point format) or double precision 
floating point value. 


arg_DOUBLEREAL 


The argument is a quadword in size and is passed in a pair of 
parameter passing FPRs, f 1 through f 8, or in memory. The 
argument is an extended precision floating point value. 
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4.4 Return Values 

The following table details how return values are to be handled. 



Table 4-4: Return Value Types and Actions 



Type 


Action 


* Single precision floating point 

* Double precision floating point 


Return in f l. The return value is rounded to 
single precision for the return value type of single 
precision floating point. 


• Extended precision floating 
point 


Return the lower-addressed doubleword in f l 
and the higher-addressed doubleword in f 2. 


• 8-bit, 16-bit or 32-bit integer 

• Pointer 


Return in r3. Return values smaller than 32 bits 
in size are sign or zero extended as appropriate 
to 32 bits. 


• 64-bit integer 


Return the lower-addressed word in r3 and the 
higher-addressed word in r4. 


• Structure or union < 8 bytes in 
size 


Return the lower-addressed word in r3 and the 
higher-addressed word in r4 as if it were first 
stored in an 8 byte aligned memory area. Bits 
beyond the last member of the structure or union 
are not defined. 


• Structure or union > 8 bytes in 
size 


These shall be returned in a memory area 
allocated by the caller whose address is passed 
to the called function as a hidden first parameter 
in r3. This causes gr to be initialized to 4 rather 
than 3 in § 4.3, "Parameter Passing". 
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5 System Object Model (SOM) Binary Interface 

IBM's System Object Model (or SOM) provides a language-neutral binary interface for object- 
oriented (00) class libraries. A SOM class library is a collection of one or more SOM classes 
whose functionality is accessible via interface descriptions expressed in OMG's (Object 
Management Group, Inc.) Interface Definition Language (IDL). Every SOM class is 
implemented with a procedure that constructs and registers the class and a set of method 
procedures that implement the methods defined for the class. A SOM class library may be 
realized as a dynamically linked library (DLL) on platforms that provide dynamic linking, or a 
set of object files contained in a static library on platforms that do not. Programmers typically 
make use of SOM class libraries through language bindings that map the IDL interface 
descriptions into a particular programming language or through SOM-aware language 
compilers that produce code directly to the SOM binary interface. 

The SOM Kernel is a distinguished class library that contains the SOM kernel classes and 
implements all of the basic mechanisms and general 00 capabilities used in creating and 
manipulating all other SOM classes and their object instances. Except for the fact that all of 
the SOM Kernel functions and global variables are also included as part of this library, it is in 
most other respects no different from any other SOM class library. 

All of the 00 constructs provided by SOM are ultimately expressed in terms of a small 
number of function calls and data structures. Some of these are used to construct classes 
and exercise the method resolution mechanisms (among other things) and hence, in turn, 
permit the instantiation of objects and the invocation of methods on objects. The remainder 
of the SOM Kernel is made up of methods supplied with the three built-in classes 
(soMObj ect, soMClass, and soMClassMgr). Generally speaking, most of SOM is 
implemented as methods (in preference to functions), to permit user specialization through 
normal 00 subclassing, but some critical or heavily used constructs are implemented as 
ordinary functions. 

The binary interface to SOM is the substrate upon which the language bindings are built. It 
consists of 

• Addressing, calling conventions, and register usage. 

• Class library organization. 

• The representation of objects and object references. 

• The data structures used for method resolution and basic operations. 

• The kernel functions used to perform class construction and method resolution. 

The remaining SOM Kernel functions and methods can be invoked and applied using this 
basic set of mechanisms. 

Some of the functions included in IBM implementations of the SOM Kernel library are 
provided as a convenience for programmers doing SOM development on IBM platforms. 
These functions are not required to be available in conforming SOM implementations from 
other vendors. In this category are functions that provide debugging support and formatted 
stream output. A list of mandatory and optional kernel functions is given in § 5.8, "SOM 
Kernel Functions", on page 48. 
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Consult the SOMObjects Developer Toolkit Programmer's Reference ManuaHor more 
detailed descriptions and specifications of particular kernel functions and methods. 
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5.1 Addressing, Calling Conventions, and Register Usage 

All addresses used in SOM are 32-bit addresses. SOM utilizes the standard system function 
calling convention defined in § 4, "Procedure Linkage Conventions", on page 21 for all 
function and method calls. 
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5.2 SOM Class Library Structure 

A SOM class library contains the implementation of one or more SOM classes. Normally 
each class in a SOM class library exports at least one function named 
<classivame>NewClass and two data structures, ClassData named 

<classJVame>ClassData and auxiliary ClassData named <classIVame>CClassData. 

Additional functions and data structures may also be exported but these are not mandated 
by SOM. We say "normally" because it is possible to construct a SOM class library without 
these characteristics, but a SOM class without these exports does not offer a client 
programmer the opportunity to utilize SOM's offset (or static) method resolution mechanism. 
(The offset method resolution mechanism provides the best performance and is the most 
commonly employed form of SOM method resolution. Providers of SOM class libraries give 
client programmers the most options by offering support for offset method resolution and 
leaving the decision of whether or not to use it to the client programmer.) Typically both the 
<classIVame>NewClass function and the <classIVame>ClassData and 

<classivame>cciassData structures are generated automatically by the SOM Compiler as 
part of its implementation bindings for a language or produced implicitly by a "Direct-to-SOM" 
compiler. 

The <classivame>NewClass function constructs, registers with the SOM Class Manager, 
and returns to the caller, a SOM class object representing the class designated in its name. 
This function is idempotent. To make it easy to write a <classivame>NewClass function by 
hand, the SOM Kernel library includes a function named somBuildciass which can 
perform all of these functions based on parameters provided by the caller. 

The ClassData structure reflects the releaseorder modifier from the implementation section 
of the class' IDL specification. The "release order" is a linear ordering of all of the attributes, 
methods, and public data introduced by the class; attributes, methods, or public data items 
inherited by the class are not included. As newer releases of a class library appear this list 
may change, but only by extension at the end. Even if a method has been refactored up into 
one of its ancestor classes (and now appears in that class' release order), its original position 
in the release order of the class where it was first introduced is always maintained. Except 
for the first member of the ClassData structure (which always points to the actual SOM class 
object) each of its member elements corresponds directly to a release order item and is 
referred to as a token. The tokens are classified as either a method token or a data token. 
Method tokens are in reality thunks that can be called to perform SOM offset method 
resolution. They can also be passed to the somResolve function (along with a target object) 
in order to obtain a direct pointer to a method procedure. 

The contents of the <classivame>ciassData structure are computed during the execution 
of the <classWame>NewClass function (commonly by somBuildciass) and remain 
usable for the life of the class. The first element in the ClassData structure is a pointer to the 
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class object (all SOM classes are represented by run-time class objects). The remainder of 
the ClassData structure has one element for each item in the release order. 

Figure 5-1 : ClassData Structure 



Offset 
0 



12 



Pointer to the class object 



Token for 1st element in 
release order 



Token for 2nd element in 
release order 



Token for 3rd element in 
release order 



See Figure 5-4, "SOM 
Object and Object 
Reference" 



Tokens are opaque, but method tokens are 
known to be thunks (callable). 



The <className>cciassData is an auxiliary structure that is also computed during the 
construction of a class. (The "C" in the name of this structure is an artifact of its evolution and 
is not otherwise meaningful). It contains information that may be used by SOM language 
bindings and "Direct-to-SOM" compilers, such as a list of method table structures for the 
class and its parent classes. This structure is not generally of direct interest to users of a 
SOM class since the information in this structure can be obtained dynamically through 
queries to the class object. By exporting it in this form, more efficient static references can 
also be built into language bindings. 

Figure 5-2: Auxiliary ClassData Structure 



Offset 






0 






See Figure 5-3, 






Pointer to parentMtab list 




"som ParentMtabStruct 
Structure" 
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Data token for instance data 
introduced by this class 








The remainder of the structure is opaque. 
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The somParentMtabstruct, pointed at by the first element of the auxiliary structure 
Figure 5-3: somParentMtabstruct Structure 



Offset 
0 



Pointer to somMethodTab 



Pointer to the class object 



Pointer to 

somRenewNoInitNoZero 
thunk 



Reserved 



See Figure 5-5, 
"somMethodTab 
Structure" 



See Figure 5-4, "SOM 
Object and Object 
Reference" 



contains a pointer to a somRenewNoInitNoZero thunk. This thunk provides support for 
object creation very similar to the somRenewNoInitNoZero method. If the metaclass of the 
object being created is soMClass, invoking the thunk results in a fast object instance 
creation. However, if the metaclass of the object is not soMClass, the thunk will end up 
invoking the somRenewNoInitNoZero method. The SOM API requires that 
somRenewNoInitNoZero always be called when creating a new object whose metaclass is 
not soMClass. This is because metaclasses must be guaranteed that they can use 
somRenewNoInitNoZero to track object creation if this is desired. In either case, a new 
instance of the receiving class is created by setting the appropriate location in the passed 
memory block to the receiving class' instance method table. Unlike somNew, no space is 
allocated. It is the callers responsibility to allocate space which is large enough to hold an 
instance of the receiving class. The SOM method somGetinstanceSize can be invoked 
on the class to determine the amount of memory required. A pointer to this allocated space is 
passed in the call. 

A dynamically linked class library is one that can be loaded or unloaded by the SOM class 
manager (statically linked class libraries cannot be loaded or unloaded, although their 
classes can be created and destroyed). Each dynamically linked class library is required to 
provide a special library initialization function (one per library) that can be automatically 
invoked whenever the library is loaded. One some platforms the operating system will invoke 
this function. On platforms where the operating system does not provide this capability, the 
SOM class manager will invoke a function named soMinitModule which the library is then 
expected to provide. This library initialization function is responsible for creating and 
registering class objects for all of the classes in the library. 
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5.3 SOM Objects and Object References 

SOM objects are variable in length and semi-opaque. They are composed of two parts: a 
method table pointer and an optional instance data section. The method table pointer is 
found at offset 0 in every SOM object. The instance data section (if it exists) is the opaque 
part. It is laid out according to the class of the object. Each class that contributes to the 
derivation of the object's class will have a unique portion of the instance data section, 
appropriately aligned, to hold its instance data (if any). The layout of this data is known only 
to the code that implements each of the contributing classes. 



SOM object references are simply pointers to SOM objects. 

The format of a SOM object and a SOM object reference is illustrated below. 

Figure 5-4: SOM Object and Object Reference 



Object Reference 



Pointer to 
object 



Offset 



Pointer to 
somMethodTab 



Instance data 
section 

Object 



See Figure 5-5, 
"somMethodTab 
Structure" 



Instance data is opaque. 
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5.4 SOM Method Table 

All SOM objects point to a data structure referred to as a method table. A SOM method table 
is the principal data structure employed by the offset resolution mechanism. This structure is 
owned by the class object and created during class initialization. Even classes that do not 
support offset resolution must provide a method table, although in this case, no entries are 
needed in the entry section. The SOM method table is semi-opaque. It consists of a fixed 
section that holds class-related information, and a variable section containing an array of 
entries. Entries are opaque and only used internally by SOM. They may include such things 
as pointers to method procedures, redispatch stubs, interface identifiers, etc. A block 
diagram of a SOM method table is shown below. 



Figure 5-5: somMethodTab Structure 



Offset 
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16 
20 
24 
28 



Pointer to class object 



Pointer to class information 



Pointer to the class name 



Instance size 



Reserved 



Reserved 



Reserved 



Reserved 



See Figure 5-4, "SOM 
Object and Object 
Reference" 



Opaque 



Null-terminated string 



1 st Entry 



Start of Entry Array is opaque and the entry 
contents are opaque. 
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5.5 SOM Ids 



Many commonly used methods in the SOM Kernel library refer to class names and method 
names. To keep these operations as efficient as possible, class names and method names 
are represented in a special form referred to as a somld. The somld form permits very rapid 
string comparisons. 

Somlds can be statically declared as literals in a program or generated dynamically during 
program execution from strings. A statically declared somld goes through a transformation 
during its first use which involves registering its value and computing a unique key for it. The 

Figure 5-6: Statically Initialized somld 



Before First Use 

somld myClass = (somld) &myClassInitValue ; 



pointer 



char myClassInitValue [] = "MyClass"; 
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After First Use 

somld myClass; 



[Opaque] 



programmer need not be concerned with this transformation as it is performed automatically 
by any of the SOM Kernel functions that operate on somlds. To subsequently re-extract the 
string value from a somld, the somStringFromid function must be used. Somlds can also 
be manufactured dynamically using the somidFromString function. Somlds created in this 
manner must be subsequently freed when they are no longer needed. 

If it is known that the strings used to create somlds will exist for the life of the process, then 
the creation of somlds can be significantly optimized using a persistent somld bracket. To 
start a persistent somld bracket call the SOM Kernel function somBeginPersistentids. 
Thereafter all subsequent derivations of somlds from strings occurring in the same thread of 
execution will assume that the string values will persist for the remainder of the process. To 
end a persistent somld bracket simply call the somEndPersistentids function. 
Subsequently any somlds manufactured from strings on the same execution thread will not 
be assumed to persist. 
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5.6 Basic Operations 

In order for any process to make use of SOM, it must first initialize the SOM Kernel by calling 
the function somEnvironmentNew (SOM language bindings typically hide this requirement). 
This function takes no arguments and is idempotent. It performs any needed SOM 
initialization and returns an object reference for an instance of the soMClassMgr class. 
SOM initialization includes the construction of class objects for each of the built-in classes 
and the instantiation of a single instance of the soMClassMgr. This object can be 
subsequently used to locate class objects and to load and unload dynamically linked SOM 
Class libraries. After initialization has completed, the soMClassMgrObj ect external 
variable in the SOM Kernel library also contains an object reference for the single instance of 
the soMClassMgr. This external reference permits compiled programs to refer statically to 
the SOM class manager. 

Once the SOM environment has been initialized, four SOM objects exist. Three of them are 
class objects; the fourth is the soMClassMgrOb j ect, usually just referred to as the SOM 
class manager. SOM is now ready to perform basic operations such as subclassing and 
method resolution. Subclassing involves the creation of a new class and is done by calling 
the SOM Kernel function somBuildciass. The somBuildciass function is simply a 
carefully sequenced invocation of methods provided by the built-in class soMClass, and 
based on descriptive information passed as arguments to somBuildciass. 

Since other basic operations such as object instantiation and deinstantiation (freeing objects) 
are performed by invoking methods on objects (frequently class objects), the remainder of 
the SOM binary interface reduces to exercising the method resolutions mechanisms. 
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5.7 Method Resolution Mechanisms 

SOM provides three different method resolution mechanisms: offset, name lookup, and 
dispatch. Implementors of SOM classes decide which of these mechanisms their class will 
support. If a class supports the offset method resolution mechanism, then a client 
programmer may use any of the offset, name lookup, or dispatch mechanisms when invoking 
its methods. If a class supports name lookup but not offset, then a client programmer may 
use either the name lookup or dispatch mechanism. All SOM classes always support the 
dispatch resolution mechanism. 

Classes that support the offset method resolution mechanism have interfaces declared in 
IDL and export a <className>ciassData structure. Classes that support name lookup, 
but not offset resolution may have interfaces declared in IDL, but all methods not supporting 
offset resolution must have the namelookup modifier attached to them. Classes that support 
neither the offset nor the name lookup mechanism do not declare their methods in IDL at all 
(unless as comments), and need not supply any IDL definition of the class itself, since no 
static language bindings are provided. Finally, a class may have methods with a mixed level 
of support. That is, some of its methods would be accessible via the offset, name lookup, or 
dispatch mechanisms, while others would only be accessible using the name lookup or 
dispatch mechanisms, with yet other methods only accessible via the dispatch mechanism. 
All methods of all SOM classes are always accessible via the dispatch mechanism. 

Most SOM class implementors provide implementations that support offset method 
resolution, because it offers the best performance and gives client programmers their choice 
of any of the three method resolution mechanisms. 

5.7.1 Using Offset Method Resolution 

The ClassData structure can be used to perform offset method resolution. Offset method 
resolution is appropriate whenever the class that introduced the method and the name and 
signature of the method to invoke are all known at compile-time. It offers a highly optimized 
execution path for invoking a method. In SOM, the method tokens in the ClassData structure 
are actually method resolution thunks, and invoking a method is achieved by simply calling 
the appropriate thunk with the arguments needed for the method procedure (the receiving 
object is always the first argument in this list). 

Following is a typical offset method resolution method call. 



Figure 5-7: Example Offset Method Resolution Method Call 



# 


assume 


GOT address in r31 




mr 


%r3 , <ARG1> # Pointer to receiving object 




mr 


%r4, <ARG2> # argument 2 




mr 


%r5, <ARG3> # argument 3 


# 


call < 


introducingClassName>Cla.ss'Data. . <methodName> 




lwz 


%rll, <introducingClassName>Class~Data@got (%r31) 




lwz 


%rl 1 , <methodName> ( %rll ) # offset into ClassData 




mtctr 


%rll 




bctrl 




# 


r3 now 


contains the result from the method procedure 
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If it is known that the same method is going to be repeatedly invoked on one or more 
instances of the same class, a pointer to the actual method procedure selected by offset 
resolution can be obtained once and the method procedure can then be repeatedly called 
through the pointer. The SOM Kernel function somResolve is used to obtain the method 
procedure pointer from the target object and method token. 

Method procedures may wish to invoke implementations inherited from one or more parent 
classes. To do so using the offset resolution mechanism, the auxiliary ClassData structure 
must be used. When a class is derived from other classes, its immediate parent classes are 
specified using a linear ordering when the somBuildciass function is invoked. That 
ordering is preserved by the parentMtab member in the <classi\7ame>cciassData 
structure, which contains a list of method tables for the class and each of its immediate 
parent classes. For example to invoke an implementation of the method f oo provided by the 
2nd parent class from inside the method procedure for f oo in class bar, the following 
sequence could be used. 



Figure 5-8: Example Offset Method Resolution Parent Method Call 



# 


assume 


GOT 


address in r31 




lwz 


%r3 , 


barCClassData@got (%r31) 




lwz 


%r3, 


parentMtab ( %r3 ) # offset into CClassData 




addi 


%r4, 


0,2 # Specify 2nd direct parent class 




lwz 


%r5 , 


<introducingClassI\J'ame>ClassData(agot ( rGOT) 




lwz 


%r5, 


foo(%r5) # offset into ClassData 




bl 


somParentNumRe solve 




mtctr 


%r3 


# parent method procedure pointer 




mr 


%r3, 


<ARG1> # Pointer to receiving object 




mr 


%r4, 


<ARG2> # argument 2 




mr 


%r5, 


<ARG3> # argument 3 




bctrl 






# 


r3 now 


contains the result from the method procedure 



5.7.2 Using Name Lookup Method Resolution 

Name lookup method resolution is appropriate whenever the method signature is known at 
compile time but the name of the introducing class or the method name itself is not known at 
compile time. 



The name lookup method resolution mechanism can be exercised in several ways. The 
easiest way is to call the SOM Kernel function somResolveByName, which takes a target 
object and a method name in the form of a null-terminated string, and returns a method 
procedure pointer. However, better performance and finer grain control over the name lookup 
mechanism is available through the use of several class methods provided by the 

implementation of SOMClass. These are somLookupMethod, somFindMethod, 
somFindMethodOK, somFindSMethod, and somFindSMethodOK. These methods all 

represent the method name as a somld, offer different calling sequences, provide different 
failure modes, and in the case of the somFindSMethod limit their resolution to methods 
which are statically defined. However, since all of these mechanisms are provided as 
methods themselves, they must be invoked either by the offset resolution mechanism 
described above, the somResolveByName kernel function, or using dispatch resolution, 
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described in the next section. The quickest way to invoke one of the name lookup methods 
is, of course, by using offset resolution. 

5.7.3 Using Dispatch Method Resolution 

The dispatch method resolution mechanism is appropriate whenever the method signature 
itself is not known at compile time. The name of the method (in the form of a somld), a 
memory area to hold any result value produced by the method, and a data structure that 
contains all of the arguments needed for the method are all supplied as arguments to the 
dispatch mechanism. 

The dispatch resolution mechanism is available through the soMObject method 
somDispatch. Because somDispatch is implemented as a method it must be invoked 
using offset or name lookup method resolution (it could also be invoked using the dispatch 
resolution mechanism, but then you must readdress the question of how you resolve the 
outer somDispatch method). 
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5.8 SOM Kernel Functions 

5.8.1 Required Functions 

These functions are required in all conforming SOM implementations. 

SOMClassMgrNewClass 
SOMClassNewClass 
SOMObj ectNewClass 
somAncestorRe solve 
somApply 

somBeginPer si stent Ids 

somBuildClass 

somCalllnit If Should 

somCheckld 

somCl as sRe solve 

somComparelds 

somCreateDynamicClass 

somDataRe solve 

somDataResolveChk 

somEndPersistent Ids 

somEnvironmentNew 

somExceptionld 

somExceptionValue 

somExceptionFree 

somGet Global Environment 

somldFromString 

somlsObj 

somParentNumRe solve 

somPrintf 

somRegisterld 

somResolve 

somResolveByName 

somSet Except ion 

somSetExpectedlds 

somStringFromld 

somTestCls 

somTotalReglds 

somUniqueKey 

somVprintf 

5.8.2 Optional Functions 

These are optional debugging support functions provided in IBM implementations of SOM. 

somAssert 
somCheckArgs 
somLprintf 
somPref ixLevel 
somTest 

5.8.3 Obsolete Functions 

These are obsolete functions provided for SOM 1 .0 compatibility in IBM implementations of 
SOM. 

somCons t rue t Class 
somParent Re solve 
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5.9 SOM Kernel External Variables 

5.9.1 Required External Variables 

These external variables are required in all conforming SOM implementations. 

• Variables that are pointers to user-replaceable functions 

SOMCalloc 

SOMClassInitFuncName 

SOMDeleteModule 

SOMError 

SOMFree 

SOMLoadModule 

SOMMalloc 

SOMOutCharRoutine 

SOMRealloc 

• External data structures 

SOMClassCClassData 

SOMClassClassData 

SOMClassMgrCClassData 

SOMClassMgrClassData 

SOMClassMgrObj ect 

SOMObj ectCClassData 

SOMObj ectClassData 

SOM_IdTable 

SOM_IdTableSize 

SOM_Maj orVersion 

SOM_MinorVersion 

5.9.2 Optional External Variables 

These are optional debugging support variables found in IBM implementations of SOM. 

SOM_AssertLevel 
SOM_TraceLevel 
SOM WarnLevel 
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5.10 SOM Kernel Class' Release Order 

5.10.1 SOMObject 

somlnit 

somUninit 

somFree 

<reserved 1> 

somGetClassName 

somGetClass 

somlsA 

somRespondsTo 

somlsInstanceOf 

somGetSize 

somDumpSelf 

somDumpSelf Int 

somPrintSelf 

<reserved 2> 

somDispatch 

somClassDispatch 

5.10.2 SOMCIassMgr 

somFindClsInFile 

somFindClass 

somClassFromld 

somRegisterClass 

somUnregisterClass 

somLocateClassFile 

somUnloadClassFile 

somGet Init Function 

somMergelnto 

somGetRelatedClasses 

somSubstituteClass 

_get_somInterf aceRepository 

_set_somInterf aceRepository 

_get_somRegisteredClasses 

5.10.3 SOMCIass 

somNew 

somRenew 

somClassReady 

somGetName 

somDescendedFrom 

somCheckVersion 

somFindMethod 

somFindMethodOK 

somSupportsMethod 

somGetNumMethods 

somGet Ins tanceSize 

somGet Inst ancePartSize 

somGetMethodlndex 

somGetNumStat icMethods 

somGet PclsMtab 

somGet ClassMtab 

somAddStaticMethod 

somOverrideSMethod 

somAddDynamicMethod 

somFindSMethod 
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somFindSMethodOK 

somGetMethodDescriptor 

somGetNthMethodlnf o 

somSetClassData 

somGetClassData 

somNewNoInit 

somRenewNoIn.it 

somGetlnstanceToken 

somGetMemberToken 

somSetMethodDescriptor 

somGetMethodData 

somOverrideMtab 

somGetMethodToken 

soraGet Parents 

somGetPclsMtabs 

somlnitMIClass 

somGetVersionNumbers 

somLookupMethod 

_get_somInstanceDataOf f sets 

somRenewNoZero 

somRenewNoInitNoZero 

somAllocate 

somDeal locate 

somGetRdStub 

somGetNthMethodData 
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6 System Object Exception Handling 

This chapter will explain the model and interfaces to support system object exception 
handling. This chapter will be provided in a future release of this document. 
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7 Execution Model 

This chapter discusses the execution model for programs conforming to this ABI. It also 
provides code examples demonstrating function tags and how fundamental operations such 
as function calls and data access can be performed. 
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7.1 Code Model 

The code model supported by this ABI is the Position Independent Code (PIC) model. 
Instructions in this code model generally hold only relative addresses and not absolute 
addresses. PIC code segments can be loaded at any virtual address in memory and execute 
properly. Code segments containing absolute addresses will only execute properly if loaded 
at a specific virtual address making the absolute addresses contained in the instructions 
coincide with the instruction's virtual addresses. This ABI specifies that both executables and 
dynamic link libraries shall contain position independent code. The use of absolute code (i.e. 
position dependent code) is not supported by the ABI and is non-conforming. 



System V ABI Note: The System V Application Binary Interface, PowerPC Processor 
Supplement specifies that executables use the absolute code model. This ABI specifies 
that executables use the position independent code model. 



When the system creates the process image from an executable and various dynamic link 
libraries, the system chooses the virtual addresses at which the load segments in the load 
modules will be loaded. With position independent code, the system loader can load the 
code segments at any virtual address and the code will function correctly. 

Position independent code relies on two techniques. 

• Instructions which transfer control (e.g. branch instructions) either contain an address 
relative to the virtual address of the instruction or use registers to hold the target 
address. A relative branch instruction computes its target address in terms of a positive 
or negative displacement from the virtual address of the instruction. 

• When an absolute address is required, the program must compute it. Rather than 
embedding absolute addresses in the instruction stream, the compiler emits code that 
computes the needed address during execution. 

The architecture of the PowerPC processor provides for both relative branch instructions and 
branch instructions that utilize a target address contained in a register. This provides support 
for the first technique above. 

The Global Offset Table (GOT) is used in support of the second technique. The Global Offset 
Table holds the absolute addresses that cannot be held in position independent code. The 
position independent code obtains the addresses of memory objects from the GOT and can 
then access the objects. Each load module that requires such an absolute address will 
contain a GOT. The GOT for each load module is relocated by the system when the process 
image is built to contain the proper absolute virtual addresses. See § 11 .5, "Global Offset 
Table (GOT)", on page 135 for more details. 

Additionally, the Procedure Linkage Table (PLT) is used to redirect calls to functions outside 
the load module. Since the absolute address of the target function is not known until the 
process image is created, the PLT is used as an intermediary to transfer control between 
load modules. Each load module that calls functions external to the load module will contain 
a PLT. The PLT for each load module is updated by the system when the process image is 
built to contain the proper instructions to transfer control to the absolute address of the target 
function. See § 11 .6, "Procedure Linkage Table (PLT)", on page 137 for more details. 
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The use of the PLT does not affect the code generated to make functions calls. The same 
code is used for intra-module and inter-module calls with the static linker redirecting calls to 
the PLT as necessary. However, the use of the GOT does have impact on the code 
generated to access data objects. Functions must contain code to establish addressability to 
the GOT and code to access the GOT to obtain the desired absolute addresses. Example 
code can be found in § 7.3, "Code Examples". 

Due to the processor's architecture, there are two position independent code models: "small 
model" and "large model". The choice between the models is based upon a trade-off 
between the efficiency of the code and the supported size of the Global Offset Table. The 
small model supports a GOT up to 64K bytes in size (16384 entries) and has more efficient 
code than the large model. If support for a GOT with greater than 1 6384 entries is required, 
then the more general and less efficient large model should be used. Where applicable, code 
examples of both models will be shown in § 7.3, "Code Examples". 
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7.2 Function Tags 

Function tags provide a means of determining the contents of non-volatile registers as they 
were when a function was entered. Each function shall be immediately preceded by a 
function tag word. Given the address of the next instruction to be executed, an exception 
handler or debugger can search the text towards lower addresses looking for a function tag. 
Using the information in the function tag and the stack frame layout (specified in § 4.2, "Stack 
Frames", on page 25), the contents of the non-volatile registers at function entry can be 
determined. 

Function tag words are recognized by having bits 0-5 set to zero, which makes the word a 
reserved or illegal instruction. A special degenerative form of the function tag word is 
recognized. This is a zero word. If a compiler (or assembly programmer) does not support 
function tag words as described in this section, then this special form of the tag word shall be 
placed immediately before the function. This enables an exception handler or debugger to 
locate this tag word and recognize that it is not possible to determine the contents of the non- 
volatile registers as they were at function entry. Appropriate action can then be taken. 

Note: All functions shall be preceded by a function tag word. The function tag word shall be 
immediately followed by the first instruction of the function. The function tag word shall 
be either the function tag word described in this section or the special degenerative 
form of the function tag word (a zero word). 

The following table describes the format of the function tag word. Bit 0 is the most significant 
bit in the word and all tag words are stored using the data encoding specified in the ELF 
header. 



Table 7-1 : Function Tag Word 



Field Name 


Bit(s) 


Field Description 


identifier 


0-5 


This field identifies the word as a function tag and contains 
the value zero. 


version 


6-7 


This field contains the function tag version number. The 
current version is zero. 


range 


8-15 


This field contains the number of words (instructions) 
between the function tag and the first address at which the 
stack frame has been acquired and the non-volatile registers 
specified by this tag have been saved. At the end of this 
interval, the non-volatile registers still contain the values they 
had at function entry. 

Note: This field may not contain zero unless either 
long form is one or lr inreg is one. 



58 



Release 1 



Execution Model 



Table 7-1 : Function Tag Word (Continued) 



Field Name 


Bit(s) 


Field Description 


_L Ully J_ D J_ [LL 


_L D 


Thic hit cnooifioc \A/hothor tho fimr'tinn tan hac Innn fni-m 

1 1 No UIL oUcUIMco VvllcLllGl LIlG IUIIULIUII LdLJ lido IUIIL) IUIIII 

function tag information. If this bit is zero, then the function 
tag does not have long form function tag information. 
If this bit is one, then the next lower-addressed word than 
this function tag word contains a signed offset from the 
address of the function tag word to the long form function tag 
information for this function (in the . tag section). See 
§ 7.2.1 , "Long Form Function Tag Information", on page 60 
for details of the long form tag information. 


i - \r t~i y~-i ^ r~i ^ i - 


1 1 


Thic hit cnor*ifioc if a r*nmnilor"-cnor*ifir* tnkon ic nroc ant Thic 

I 1 lib UIL oUcOl 1 Ico II d OUI 1 1 Ullcl ofJcOl 1 IL- LUrxcl 1 lo pi cocl IL. 1 1 1 lo 

token may contain any value and can be used by the 
compiler for any reason. If this bit is zero, then no token is 
present. 

If this bit is one, then a token is present. If long form is 
zero, then the next lower-addressed word than this function 
tag word contains the token. If long form is one, then the 
token is contained in the next lower-addressed word than 
the long form signed offset for this function tag word. 


cj"pir31 nosav6 


± O 


Thic hit cr^o^ifioc if l r*orti^ir*otoc in tho co\/inpi i~if nnn- 

i iiio uii opcuiiico ii rj5_L fjcii Lioifjcutrb ill nic odviiiy ui iiuii 

volatile GPRs. If this bit is zero, then space for r3i is 
allocated in the GPR save area of the stack frame (if non- 
volatile GPRs are saved). 

If this bit is one, then the function does not modify r3i and 
no space for r3i is allocated in the GPR save area of the 
stack frame (if non-volatile GPRs are saved) and r3i is not 
saved. When this bit is set, r3 0 is stored at the highest 
addressed word of the GPR save area of the stack frame. 


alloca gpr30 


19 


This bit specifies if the function uses r3 0 to hold the frame 
pointer to the local variable area of the stack frame. This 
may occur if dynamic stack space allocation is used. (See 
§ 7.3.4, "Dynamic Stack Space Allocation", on page 74.) 
If this bit is zero, then r3 0 does not hold the frame pointer. If 
this bit is one, then r3 0 holds the frame pointer to the local 
variable area of the stack frame. 


lr inreg 


20 


This bit specifies where the value of lr at function entry can 
be found. If this bit is zero, then the lr save word of the 
previous stack frame contains the value of lr as it was at 
function entry. 

If this bit is one, then lr contains the value of lr as it was at 
function entry. 
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Table 7-1 : Function Tag Word (Continued) 



Field Name 


Bit(s) 


Field Description 


cr saved 


21 


This bit specifies if cr has been saved in the cr save word 
of the stack frame. If this bit is zero, then cr has not been 
saved in the cr save word of the stack frame 
If this bit is one, then the cr save word of the stack frame 
contains the value of cr as it was at function entry. 


fpr space 


22-26 


This field contains the size in doublewords of the FPR save 
area of the stack frame. If long form is zero, then all the 
non-volatile FPRs implied by this field must be saved by the 
end of the range of this function tag. 
If long form is one, then the long form function tag 
information specifies the ranges where the non-volatile 
FPRs are saved. This field merely indicates the size of the 
FPR save area in the stack frame. 


gpr space 


27-31 


This field contains the size in words of the GPR save area of 
the stack frame. If long form is zero, then all the non- 
volatile GPRs implied by this field (and gpr3i nosave) 
must be saved by the end of the range of this function tag. 
If long form is one, then the long form function tag 
information specifies the ranges where the non-volatile 
GPRs are saved. This field merely indicates the size of the 
GPR save area in the stack frame. 



7.2.1 Long Form Function Tag Information 

Functions which intersperse saving some non-volatile registers with using other non-volatile 
registers (i.e. functions that do not save all used non-volatile registers in the function 
prologue and delay saving some or all used non-volatile registers until later in the function) 
will need to use the long form function tag information to specify when the non-volatile 
registers have been saved in the stack frame. The long form function tag information is not 
stored in-line with the program instructions like the function tag words but is stored in the 
. tags section and the in-line function tag has a signed offset to the long form function 
information. The long form function tag information for a function consists of a sequence of 
entries, each two words in size, describing a range of instructions in the function. 

The following tables describe the two-word long form function tag information entries. The 
first word, word 1 , is the lowest addressed word of the two-word entry. Bit 0 is the most 
significant bit in the word and all words are stored using the data encoding specified in the 
ELF header. 
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Table 7-2: Long Form Function Tag Information, Word 1 



Fipld Namp 

1 IV 1 VI 1 ■ Ul 1 1 w 




Fipld Dpsrrintion 


range 


0-13 


This field contains the number of words (instructions) 
between the end of the previous range (in the function tag 
word, if this is the first long form function tag information 
entry, or in the previous long form function tag information 
entry) and the first address at which the non-volatile 
registers specified by this tag have been saved. At the end 
of this range, the non-volatile registers that were saved 
during this range still contain the values they had at function 
entry. 


fpr saved 


14-31 


This field contains one bit for each non-volatile FPR. The 
most significant bit represents f 14 and the least significant 
bit represents f 31. 

If a bit is zero, then the corresponding FPR has not been 
saved in the appropriate place in the FPR save area of the 
stack frame. If a bit is one, then the corresponding FPR has 
been saved in the appropriate place in the FPR save area of 
the stack frame. 


Table 7-3: Long Form Function Tag Information, Word 2 


Field Name 


Bit(s) 


Field Description 


last entry 


0 


This bit specifies if this entry is the last entry in the sequence 

of long form function tag information entries for a function. If 

this bit is zero, then this entry is immediately followed by 

another entry for this function. 

If this bit is one, then this entry is the last entry for this 

function. 


reserved 


1-6 


These bits are reserved and shall contain zero. 


alloca gpr 


7-11 


This field specifies if the function uses a GPR to hold a frame 
pointer to the local variable area of the stack frame. This 
may occur if dynamic stack space allocation is used. (See 
§ 7.3.4, "Dynamic Stack Space Allocation", on page 74.) 
If this field is zero, then there is no frame pointer. If this field 
is non-zero, then the field holds the register number of the 
GPR used as the frame pointer to the local variable area of 
the stack frame. 
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Table 7-3: Long Form Function Tag Information, Word 2 (Continued) 



Field Name 


Bit(s) 


Field Description 


lr inreg 


12 


This bit specifies where the value of lr at function entry can 
be found. If this bit is zero, then the lr save word of the 
previous stack frame contains the value of lr as it was at 
function entry. 

If this bit is one, then lr contains the value of lr as it was at 
function entry. 


cr saved 


13 


This bit specifies if cr has been saved in the cr save word 
of the stack frame. If this bit is zero, then cr has not been 
saved in the cr save word of the stack frame 
If this bit is one, then the cr save word of the stack frame 
contains the value of cr as it was at function entry. 


gpr saved 


14-31 


This field contains one bit for each non-volatile GPR. The 
most significant bit represents rl4 and the least significant 
bit represents r3l. 

If a bit is zero, then the corresponding GPR has not been 
saved in the appropriate place in the GPR save area of the 
stack frame. If a bit is one, then the corresponding GPR has 
been saved in the appropriate place in the GPR save area of 
the stack frame. 
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7.3 Code Examples 

The code examples in this section illustrate how operations may be done but not how they 
must be done. The examples will be a mixture of ANSI C and PowerPC assembler code but 
programming languages other than ANSI C may choose to use the same conventions 
demonstrated in the examples. However, failure to do so does not prevent a program from 
conforming to the ABI. 

The examples below are simplified code fragments and are not meant to show optimal code 
sequences or reproduce compiler-generated code. They are intended to explain the 
execution model and demonstrate concepts. 

7.3.1 Function Prologue and Epilogue 

This section provides code examples for function prologues and epilogues. A function 
prologue acquires a stack frame if necessary, and saves any non-volatile registers used by 
the function. A function epilogue "unwinds" the work done by the prologue by restoring the 
non-volatile registers and releasing the stack frame before returning to the caller. See § 4.2, 
"Stack Frames", on page 25 for the rules regarding stack frames. 

A compiler may generate in-line code to save and restore the non-volatile registers used by 
the function. However, if many non-volatile registers must be preserved, it may be more 
efficient for the compiler to generate a call to a compiler-supplied support routine which 
performs the saves or restores. Following are some examples of support routines which 
perform these functions. 

Note: The routines below rely on an address passed in the volatile register rli. Therefore 
these routines must be statically-linked into the same load module as the caller. 
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The _savef pr_n_l routines save the non-volatile FPRs n through 31 in the new stack 
frame and lr in the previous stack frame. The routines take two parameters. 

• ro shall contain the value of lr at entry to the function whose prologue called this 
routine. 

• rii shall contain the address of the word immediately following the FPR save area. This 
is also the address of the previous stack frame. 



Figure 7-1 : savefpr n_l Routines 





. word 


0 # tag word 


savefpr 14 1 


stf d 


%fl4, 


-144 (%rll) 


savefpr 15 1 


stf d 


%fl5, 


-136 (%rll) 


savefpr 16 1 


stf d 


S 1 1 6 , 


-128 ( -sr 1 1 ) 


savefpr 17 1 


stf d 


%fl7, 


-120 (%rll) 


savefpr 18 1 


stf d 


%fl8, 


-112 (%rll) 


savefpr 19 1 


stf d 


%fl9, 


-104 (%rll) 


savefpr 20 1 


stf d 


%f 20 , 


-96 (%rll) 


savefpr 21 1 


stf d 


%f21, 


-88 (%rll) 


savefpr 22 1 


stf d 


%f 22 , 


-80 (%rll) 


savefpr 23 1 


stf d 


%f 23 , 


-72 (%rll) 


savefpr 24 1 


stf d 


%f 24 , 


-64 (%rll) 


savefpr 25 1 


stf d 


%f25, 


-56 (%rll) 


savefpr 26 1 


stf d 


%f 26 , 


-48 (%rll) 


savefpr 27 1 


stf d 


%f 27 , 


-40 (%rll) 


savefpr 28 1 


stf d 


%f 28 , 


-32 (%rll) 


savefpr 29 1 


stf d 


%f 29 , 


-24 (%rll) 


savefpr 3 0 1 


stf d 


%f 30 , 


-16 (%rll) 


savefpr 31 1 


stf d 


%f31, 


-8 (%rll) 




stw 


%r0 , 4 


(%rll) 




blr 
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The _restf pr_n_l routines restore the non-volatile FPRs n through 31 , restore lr, release 
the stack frame and return to the caller of the function whose epilogue branched to this 
routine. The routines take one parameter. 

• rii shall contain the address of the word immediately following the FPR save area. This 
is also the address of the previous stack frame. 



Figure 7-2: restfpr n_l Routines 





. word 


0 # tag word 


restfpr 14 1 


lfd 




1/1/1 / 9- t- 1 1 \ 


restfpr 15 1 


lfd 


-s L ± D , 


9-vl 1 1 

-_lj5d ^-srii j 


restfpr 16 1 


lfd 


-SLID, 


no / 9-rl 1 1 


restfpr 17 1 


lfd 






restfpr 18 1 


lfd 


-o L 1 O , 


-112 (-srii) 


restfpr 19 1 


lfd 


%fl9, 


-104 (%rll) 


restfpr 20 1 


lfd 


%f 20 , 


-96 (%rll) 


restfpr 21 1 


lfd 


%f 21 , 


-88 (%rll) 


restfpr 22 1 


lfd 


%f 22 , 


-80 (%rll) 


restfpr 23 1 


lfd 


%f 23 , 


-72 (%rll) 


restfpr 24 1 


lfd 


%f 24 , 


-64 (%rll) 


restfpr 25 1 


lfd 


%f25, 


-56 (%rll) 


restfpr 26 1 


lfd 


%f 26 , 


-48 (%rll) 


restfpr 27 1 


lfd 


%f 27 , 


-40 (%rll) 


restfpr 28 1 


lfd 


%f 28 , 


-32 (%rll) 


restfpr 29 1 


lfd 


%f 29 , 


-24 (%rll) 


restfpr 30 1 


lfd 


%f 30 , 


-16 (%rll) 


restfpr 31 1 


lwz 


%r0 , 


4 (%rll) 




lfd 


%f31, 


-8 (%rll) 




mtlr 


%r0 






ori 


%rl, 


%rll, 0 




blr 
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There are two versions of the non-volatile GPR save and restore routines. The 
_savegpr_n_l and _restgpr_n_l routines are used when no non-volatile FPRs need to 
be preserved by the function. The _savegpr_n and _restgpr_n routines are used when 
non-volatile FPRs need to be preserved by the function and _savef pr_n_l and 
_restfpr_n_l routines are being used. 

The _savegpr_n_l routines save the non-volatile GPRs n through 31 in the new stack 
frame and lr in the previous stack frame. The routines take two parameters. 

• ro shall contain the value of lr at entry to the function whose prologue called this 
routine. 

• rii shall contain the address of the word immediately following the GPR save area. 
Since there is no FPR save area in the stack frame, the address in rii is also the 
address of the previous stack frame. 



Figure 7-3: _savegpr _n_l Routines 





. word 


0 # tag word 


savegpr 14 1 


stw 


%rl4 , 


-72 


(%rll) 


savegpr 15 1 


stw 


%rl5 , 


-68 


(%rll) 


savegpr 16 1 


stw 


%rl6, 


-64 


(%rll) 


savegpr 17 1 


stw 


%rl7 , 


-60 


(%rll) 


savegpr 18 1 


stw 


%rl8 , 


-56 


(%rll) 


savegpr 19 1 


stw 


%rl9 , 


-52 


(%rll) 


savegpr 2 0 1 


stw 


%r20 , 


-48 


(%rll) 


savegpr 21 1 


stw 


%r21, 


-44 


(%rll) 


savegpr 22 1 


stw 


%r22 , 


-40 


(%rll) 


savegpr 23 1 


stw 


%r23 , 


-36 


(%rll) 


savegpr 24 1 


stw 


%r24 , 


-32 


(%rll) 


savegpr 25 1 


stw 


%r25 , 


-28 


(%rll) 


savegpr 26 1 


stw 


%r26 , 


-24 


(%rll) 


savegpr 27 1 


stw 


%r27 , 


-20 


(%rll) 


savegpr 2 8 1 


stw 


%r28 , 


-16 


(%rll) 


savegpr 2 9 1 


stw 


%r29 , 


-12 


(%rll) 


savegpr 3 0 1 


stw 


%r30 , 


-8 ( 


%rll) 


savegpr 31 1 


stw 


%r31 , 


-4 ( 


%rll) 




stw 


%r0 , 4 


(%rll) 




blr 
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The _restgpr_n_l routines restore the non-volatile GPRs n through 31 , restore lr, 
release the stack frame and return to the caller of the function whose epilogue branched to 
this routine. The routines take one parameter. 

• rii shall contain the address of the word immediately following the GPR save area. 
Since there is no FPR save area in the stack frame, the address in rii is also the 
address of the previous stack frame. 



Figure 7-4: _restgpr _n_l Routines 





. word 


0 # tag word 


restgpr 14 1 


lwz 


9- v- 1 A 


-72 ( 


%rll) 


restgpr 15 1 


lwz 


9- -v- T C 

-sri d , 


-68 ( 


%rll) 


restgpr 16 1 


lwz 


■ST 1 b , 


-64 ( 


%rll) 


restgpr 17 1 


lwz 


-sri / , 


-60 ( 


%rll) 


restgpr 18 1 


lwz 


%rl8 , 


-56 ( 


%rll) 


restgpr 19 1 


lwz 


%rl9, 


-52 ( 


%rll) 


restgpr 20 1 


lwz 


%r20 , 


-48 ( 


%rll) 


restgpr 21 1 


lwz 


%r21, 


-44 ( 


%rll) 


restgpr 22 1 


lwz 


%r22 , 


-40 ( 


%rll) 


restgpr 23 1 


lwz 


%r23 , 


-36 ( 


%rll) 


restgpr 24 1 


lwz 


%r24 , 


-32 ( 


%rll) 


restgpr 25 1 


lwz 


%r25 , 


-28 ( 


%rll) 


restgpr 26 1 


lwz 


%r26 , 


-24 ( 


%rll) 


restgpr 27 1 


lwz 


%r27 , 


-20 ( 


%rll) 


restgpr 28 1 


lwz 


%r28 , 


-16 ( 


%rll) 


restgpr 29 1 


lwz 


%r29 , 


-12 ( 


%rll) 


restgpr 30 1 


lwz 


%r30 , 


-8 (% 


rll) 


restgpr 31 1 


lwz 


%r0, 


4 (%rll) 




lwz 


%r31, 


-4 (% 


rll) 




mtlr 


%r0 








ori 


%rl , 


%rll, 


0 




blr 
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After using a _savef pr_n_l routine, a _savegpr_n routine can be used to save non- 
volatile GPRs. The _savegpr_n routines save the non-volatile GPRs n through 31 in the 
new stack frame. The routines take one parameter. 

• rii shall contain the address of the word immediately following the GPR save area. 



Figure 7-5: savegpr _n Routines 





. word 


0 # tag word 


savegpr 14 


stw 


9- -v 1 A 


- i A 




savegpr 15 


stw 


^LlO, 


-bo 




savegpr 16 


stw 


STlb f 


r a 
- 64 


[ST 11 ) 


savegpr 17 


stw 


%rl7, 


-60 


(%rll) 


savegpr 18 


stw 


%rl8, 


-56 


(%rll) 


savegpr 19 


stw 


%rl9, 


-52 


(%rll) 


savegpr 2 0 


stw 


%r20 , 


-48 


(%rll) 


savegpr 21 


stw 


%r21, 


-44 


(%rll) 


savegpr 22 


stw 


%r22 , 


-40 


(%rll) 


savegpr 2 3 


stw 


%r23 , 


-36 


(%rll) 


savegpr 24 


stw 


%r24 , 


-32 


(%rll) 


savegpr 2 5 


stw 


%r25 , 


-28 


(%rll) 


savegpr 2 6 


stw 


%r26 , 


-24 


(%rll) 


savegpr 2 7 


stw 


%r27 , 


-20 


(%rll) 


savegpr 2 8 


stw 


%r28 , 


-16 


(%rll) 


savegpr 2 9 


stw 


%r29 , 


-12 


(%rll) 


savegpr 3 0 


stw 


%r30 , 


-8 ( 


%rll) 


savegpr 31 


stw 


%r31, 


-4 ( 


%rll) 




blr 
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Before using a _restf pr_n_l routine, a _restgpr_n routine can be used to restore non- 
volatile GPRs. The _restgpr_n routines restore the non-volatile GPRs n through 31 from 
the stack frame. The routines take one parameter. 

• rii shall contain the address of the word immediately following the GPR save area. 



Figure 7-6: restgpr n Routines 





. word 


0 # tag word 


restgpr 14 


lwz 




- 1 Z \ 


-o r 1 1 ; 


restgpr 15 


lwz 




"Do I 


-o r 1 1 ; 


restgpr 16 


lwz 


-s ri d , 




-srll) 


restgpr 17 


lwz 


%rl7, 


-60 ( 


%rll) 


restgpr 18 


lwz 


%rl8, 


-56 ( 


%rll) 


restgpr 19 


lwz 


%rl9, 


-52 ( 


%rll) 


restgpr 20 


lwz 


%r20 , 


-48 ( 


%rll) 


restgpr 21 


lwz 


%r21, 


-44 ( 


%rll) 


restgpr 22 


lwz 


%r22 , 


-40 ( 


%rll) 


restgpr 23 


lwz 


%r23 , 


-36 ( 


%rll) 


restgpr 24 


lwz 


%r24 , 


-32 ( 


%rll) 


restgpr 25 


lwz 


%r25 , 


-28 ( 


%rll) 


restgpr 26 


lwz 


%r26 , 


-24 ( 


%rll) 


restgpr 27 


lwz 


%r27 , 


-20 ( 


%rll) 


restgpr 28 


lwz 


%r28 , 


-16 ( 


%rll) 


restgpr 29 


lwz 


%r29 , 


-12 ( 


%rll) 


restgpr 30 


lwz 


%r30 , 


-8 (% 


rll) 


restgpr 31 


lwz 


%r31, 


-4 (% 


rll) 




blr 









Note: The Load/Store Multiple instructions should not be used because they are generally 
slower than a collection of individual register loads/stores and they also cause 
alignment exceptions in the Little Endian mode of the processor. 



If any of the non-volatile fields of cr are used, then cr must also be saved by the prologue 
and restored by the epilogue. 

A function that makes references to static data will need to establish addressability to the 
Global Offset Table. If static data references are only made within conditional code, then 
establishing addressability to the Global Offset Table can be deferred until it is known to be 
needed. See § 11.5, "Global Offset Table (GOT)", on page 135 for more information. 
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The following sample code demonstrates full non-volatile FPR and GPR saves, a cr save 
and establishing addressability to the Global Offset Table. A stack frame size of less than 
32K bytes is assumed. 



Figure 7-7: Function Prologue and Epilogue Sample Code (Small Stack) 





. word 


0x00080652 


# 


tag word 


function : 


ori 


%rll, %rl, 0 


# 


rll=address previous frame 




stwu 


%rl, -240(%rl) 


# 


acquire new frame 




mf lr 


%r0 


# 


set rO to lr 




bl 


savefpr 14 1 


# 


save lr, fl4-f31 




addi 


%rll, %rll, -144 


# 


set rll for savegpr 




bl 


savegpr 14 


# 


save rl4-r31 




mf cr 


%r0 


# 


set rO to cr 




stw 


%r0, -76(%rll) 


# 


save cr 




bl 


_GLOBAL_OFFSET_TABLE_- 4 




mf lr 


%r31 


# 


r31=GOT reference address 




addi 


%rll, %rl, 96 


# 


set rll for restgpr 




lwz 


%r0, -76(%rll) 


# 


set rO to original cr 




mtcrf 


0x38, %r0 


# 


restore non-volatile fields 




bl 


restgpr 14 


# 


restore rl4-r31 




addi 


%rll, %rl, 240 


# 


rll=address previous frame 




b 


restfpr 14 1 


# 


restore fl4-f31, lr and ret 
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The following sample code demonstrates acquiring a stack frame greater than 32K bytes in 
size, an in-line save of non-volatile GPRs and establishing addressability to the Global Offset 
Table. 



Figure 7-8: Function Prologue and Epilogue Sample Code (Large Stack) 





. word 


0x000 


80002 


# 


tag word 


function : 


ori 


%rll, 


%rl, 0 


# 


rll=address previous frame 




addis 


%rl2 , 


0, -1 


# 


set rl2 to the complement of 




addi 


%rl2 , 


%r!2, 65536- 


40016 # stack frame size (40016) 




stwux 


%rl , 


%rl, %rl2 


# 


acquire new frame 




mf lr 


%r0 




# 


set rO to lr 




stw 


%r30 , 


-8 (%rll) 


# 


save r30 




stw 


%r31 , 


-4 (%rll) 


# 


save r31 




stw 


%r0, 


4 (%rll) 


# 


save lr in previous frame 




ori 


%r30, 


%rll, 0 


# 


r30=address previous frame 




bl 


_GLOBAL_OFFSET_ 


_TABLE_- 4 




mf lr 


%r31 




# 


r31=GOT reference address 




ori 


%rll, 


%r30, 0 


# 


rll=address previous frame 




lwz 


%r0 , 


4 (%rll) 


# 


set rO to lr 




lwz 


%r30 , 


-8 (%rll) 


# 


restore r30 




lwz 


%r31 , 


-4 (%rll) 


# 


restore r31 




mtlr 


%r0 




# 


restore lr 




ori 


%rl , 


%rll, 0 


# 


release stack frame 




blr 






# 


return to caller 



7.3.2 Static Data Access 

This section demonstrates accessing data objects with static storage duration. Instructions in 
the PowerPC Architecture cannot hold 32-bit addresses and position independent code does 
not contain absolute addresses. So in order to access a static data object, the Global Offset 
Table entry for the static data object is referenced to get its absolute address. An automatic 
data object, which is resident on the stack, can be accessed relative to the stack frame 
pointer. 

In order to locate an entry in the GOT, two pieces of information are needed. First the 
reference address of the GOT needs to be computed and second the offset of the GOT entry 
from the reference address must be known. See § 7.3.1 , "Function Prologue and Epilogue", 
above for example code that establishes the reference address of the GOT. The offset of the 
GOT entry is supplied by the static linker when the load module is built. 

In the examples in this section, we will assume that the reference address of the GOT has 
already been loaded into r3i. The assembly syntax symbol@got denotes the offset of the 
GOT entry for the symbol symbol from the GOT reference address. This assumes the 
"small" code model where the offset can be represented as a signed 16-bit value. For "large" 
code model, where offsets may be larger, the assembly syntax symbol@got@ha, 
symbol@got@h, and symbol@got@l is used to denote the high-adjusted 16-bits, the high 
16-bits and the low 16-bits of the offset of the GOT entry for the symbol symbol from the 



Release 1 



71 



OS/2 Application Binary Interface for PowerPC (32-bit) 



GOT reference address. (See § 9.1 .2.3.1 , "Relocation Types", on page 1 06 for a 
mathematical description of @ha, @h and @l.) 

Figure 7-9: Static Data Access (Small Model) 



extern int src; 
extern int dst; 
extern int *ptr; 

dst = src; 



ptr 



*ptr 



&dst ; 



src ; 



# Assume r31 contains the GOT reference 

# address 



lwz 


%rll , 


src@got ( 


%r31) 


lwz 


%rl2 , 


dst@got ( 


%r31) 


lwz 


%r0 , 


0 (%rll) 




stw 


%r0 , 


0 (%rl2) 




lwz 


%r0 , 


dstOgot ( % 


r31) 


lwz 


%rl2 , 


ptr@got ( 


%r31) 


stw 


%r0 , 


0 (%rl2) 




lwz 


%rll , 


src@got ( 


%r31) 


lwz 


%rl2 , 


ptr@got ( 


%r31) 


lwz 


%r0 , 


0 (%rll) 




lwz 


%rl2 , 


0 (%rl2) 




stw 


%r0 , 


0 (%rl2) 





Figure 7-10: Static Data Access (Large Model) 



extern int src; 
extern int dst; 
extern int *ptr; 



dst 



src ; 



ptr = &dst; 



*ptr 



src ; 



# Assume r31 contains the GOT reference 

# address 



addis 


%rll , 


%r31, src@got@ha 


lwz 


%rll , 


src@got@l (%rll) 


addis 


%rl2 , 


%r31, dst@got@ha 


lwz 


%rl2 , 


dst@got@l (%rl2) 


lwz 


%r0 , 


0 (%rll) 


stw 


%r0 , 


0 (%rl2) 


addis 


%rll, 


%r31, dst@got@ha 


lwz 


%r0 , 


dst@got@l ( %rll ) 


addis 


%rl2 , 


%r31, ptr@got@ha 


lwz 


%rl2 , 


ptr@got@l (%rl2) 


stw 


%r0 , 


0 (%rl2) 


addis 


%rll , 


%r31, src@got@ha 


lwz 


%rll , 


src@got@l (%rll) 


addis 


%rl2 , 


%r31, ptr@got@ha 


lwz 


%rl2 , 


ptr@got@l (%rl2) 


lwz 


%r0 , 


0 (%rll) 


lwz 


%rl2 , 


0 (%rl2) 


stw 


%r0 , 


0 (%rl2) 
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7.3.3 Function Calls 

This section demonstrates making direct and indirect (through a pointer) function calls. The 
bl instruction is used to make direct function calls. The bi instruction is a self-relative 
branch instruction with a target branch displacement of ±32MB. This provides a potential 
limit on the size of load modules (and also on the location of the Global Offset Table and 
Procedure Linkage Table). 

The bl instruction can be used to call functions in the same load module or in a different 
load module. If the function is in a different load module, then the static linker will redirect the 
bl instruction to a PLT entry which the dynamic linker will arrange to point to the target 
function. 



Figure 7-11 : Direct Function Call 



extern void 


f unc ( ) ; 




f unc ( ) ; 




bl func 


-or indirect function calls, a bctrl (or blrl) instruction can be used. 




Figure 7-12 


: Indirect Function Call (Small Model) 


extern void 
extern void 


f unc ( ) ; 
(*ptr) 0 ; 


# Assume r31 contains the GOT reference 

# address 


ptr = f unc ; 




lwz %r0, f uncOgot ( %r3 1) 
lwz %rl2, ptrOgot (%r31) 
stw %r0, 0(%rl2) 


(*ptr) 0 ; 




lwz %rl2, ptr@got (%r31) 
lwz %r0, 0(%rl2) 
mtctr %r0 
bctrl 




Figure 7-13 


: Indirect Function Call (Large Model) 


extern void 
extern void 


f unc ( ) ; 
(*ptr) 0 ; 


# Assume r31 contains the GOT reference 

# address 


ptr = f unc ; 




addis %rll, %r31, func@got@ha 
lwz %r0, f unc@got@l ( %rl 1 ) 
addis %rl2, %r31, ptr@got@ha 
lwz %rl2, ptr@got@l (%rl2) 
stw %r0, 0(%rl2) 


(*ptr) 0 ; 




addis %rl2, %r31, ptr@got@ha 
lwz %rl2, ptr@got@l (%rl2) 
lwz %r0, 0(%rl2) 
mtctr %r0 
bctrl 
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7.3.4 Dynamic Stack Space Allocation 

The C language does not require dynamic stack space allocation within a stack frame. Stack 
frames are dynamically allocated on the stack with individual frames having static sizes, 
based upon program execution. For other languages that need dynamic stack space 
allocation, it is supported by the architecture and the procedure linkage conventions. Thus 
functions written in these languages can call C functions and vice versa. 



Figure 7-14, "Dynamic Stack Space Allocation", shows the stack frame before and after 
dynamic stack space allocation. Dynamic stack space allocation is accomplished by 
"opening" the stack frame between the local variable area and the parameter list area. 



Figure 7-14: Dynamic Stack Space Allocation 



rl 



Before Allocation 









register save areas 




local variable area 




parameter list area 




lr save word 




Back chain 



After Allocation 



rl 









register save areas 




local variable area 




Dynamic Stack Space 
Allocation 




parameter list area 




lr save word 




Back chain 



The register save area and the local variable area do not change in size or position as a 
result of the dynamic stack space allocation. The parameter list area is required by the 
procedure linkage conventions to be at a fixed offset from the stack pointer (rl), so this area 
must move when dynamic stack space allocation occurs. When this occurs, the offsets from 
the stack pointer to the local variable area change. To ensure addressability, a frame pointer 
must be established to address the local variable area (and register save areas) consistently 
throughout the function's activation. 



Dynamic stack space allocation requires the following steps. 



1 . After the stack frame has been acquired at function entry and before the first 
dynamic stack space allocation, a register is set to the value of the stack pointer. 
This register is the frame pointer and is used to reference data in the local variable 
area. The function tag word for the function shall specify the register used as the 
frame pointer. 

2. The size of the dynamic space to be allocated is rounded up to the next 1 6 byte 
multiple to maintain the stack's 16 byte alignment. 
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3. The stack pointer is decreased by the amount determined in step 2 and then the 
back chain value is copied to its new location. 

The following code examples demonstrate allocating dynamic stack space. The first example 
allocates a 256 byte space and the second example allocates a 40,000 byte space. A "Store 
Word with Update" instruction is used to allocate the stack space. This ensures that the stack 
pointer chain is always preserved. 



Figure 7-15: Dynamic Stack Space Allocation Sample Code (Small) 



ori 


%r30 , 


%rl, 0 


# 


r30=frame pointer 


lwz 


%rll, 


0 (%rl) 


# 


rll=back chain pointer 


stwu 


%rll , 


-256 (%rl) 


# 


allocate stack and set back chain 



Figure 7-16: Dynamic Stack Space Allocation Sample Code (Large) 



ori 


%r30 , 


%rl, 0 


# r30=frame pointer 


lwz 


%rll , 


0 (%rl) 


# rll=back chain pointer 


addis 


%rl2 , 


0, -1 


# set rl2 to the complement of 


addi 


%rl2 , 


%rl2, 65536 


-40000 # the allocation size (40000) 


stwux 


%rll, 


%rl, %r!2 


# allocate stack and set back chain 



The process of dynamically allocating stack space can be repeated as many times as 
necessary within a function's activation. When the function returns, the stack pointer is set to 
the back chain value which releases all of the dynamically allocated stack space along with 
the rest of the stack frame. Naturally, dynamically allocated stack space must not be 
referenced after the stack frame has been released. 



Even in the presence of exceptions or signals, the dynamic allocation process is safe. If 
dynamic stack space allocation is interrupted, one of three thing can happen. 

• The exception or signal handler can return. The dynamic allocation is resumed from the 
point of interruption. 

• The exception or signal handler can execute a non-local goto, or longjmp. The thread 
context is changed to a previous stack frame, automatically discarding the current stack 
frame including the dynamic allocation. 

• The process (or thread) can terminate. 

Regardless of when the interruption occurs during the dynamic stack space allocation, the 
result is a consistent, though possibly dead, process. 
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8 Resource File Format 

This chapter describes the format of resource files and resource collections. Resources are 
read-only data with the following usage restrictions. 

• Resources must be attached to valid load modules. 

• Resources can only be accessed via operating system-specific APIs. 

• Resources are only mapped into memory by the operating system-specific APIs. 

• Resource data may have no relocations and no code may have relocations that refer to 
the resource data. 

From the application view, resources are high-level language-independent, structured data 
that are used by applications, but are understood by the operating system. E.g. fonts, 
bitmaps, icons, dialogs. See OS/2 for an example of an operating system that uses 
resources. 
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8.1 Resource File 

A resource file is a load module format-independent file created by a resource compiler. It 
can contain many uniquely named resource collections and can be converted in to a form 
suitable for attachment to a load module. This is typically an object file with one sht_res 
section per resource collection. The static linker will take this object file as input, along with 
the other object files that contribute to the load module, and place each resource collection in 
the resultant load module as a pt_res segment. 

8.1.1 Resource File Header 

A resource file begins with a resource file header. 

Figure 8-1 : Resource File Header, Res32_File 



#define RF NIDENT 16 



typedef struct 
{ 

unsigned char 
Elf 32_Word 
Elf 32_Word 
Elf 32_Of f 
} Res32_File; 



rf_ident [RF_NIDENT] 
rf_rf size ; 
rf _rcnum; 
rf rcoff ; 



Member 



Description 



rf ident 



The initial bytes which identify this as a resource file and 
provide machine-independent data with which to decode and 
interpret the contents. See § 8.1 .2, "Resource File 
Identification", on page 79 for details. 



rf rfsize 



This member holds the resource file header's size in bytes. 



rf rcnum 



This member holds the number of resource collections in this 
resource file. 



rf rcoff 



This member holds the offset of the resource collection array. 
The offset is relative to the start of the resource file and shall 
be word aligned. There are rf_rcnum entries in the array. 



Each entry in the resource collection array is an Res32_Col structure. This structure 
contains the offset and size of a resource collection. 

Figure 8-2: Resource Collection Array Entry, Res32_Col 



typedef struct 
{ 

Elf 32_Of f 
Elf 32_Word 
} Res32_Col; 



rc_col lection ; 
rc size; 
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Figure 8-2: Resource Collection Array Entry, Res32_Col (Continued) 



Member 


Description 


rc collection 


This member holds the offset of a resource collection. The 
offset is relative to the start of the resource file and shall be 
word aligned. See § 8.2, "Resource Collection", on page 81 for 
details on resource collections. 


rc size 


This member holds the total size of the resource collection in 
bytes. 



Each resource collection must be self contained and occupy only the space in the resource 
file beginning at offset rc_collection having a length of rc_size bytes. All offsets within 
a resource collection must be relative to the start of the resource collection. 

8.1.2 Resource File Identification 

Following is a description of the rf_ident member of the resource file header. 

Table 8-1: rf ident [] Identification Indexes 



Name 



Value 



Description 



RF_MAG0 
RF_MAG1 
RF_MAG2 
RF MAG 3 



0x02 

1 E ' 
'S' 

The first 4 bytes hold a "magic number" identifying this as a 
resource file. 



RF CLASS 



Class of the data in this resource file. 



Name 


Value 


Meaning 


RESCLASSNONE 


0 


Invalid class 


RESCLASS32 


i 


32 bit architecture. This is the 
format of the data specified 
herein. 


RESCLASS64 


2 


This is reserved for 64 bit 
architectures. It is otherwise 
unspecified. 
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Table 8-1 : rf ident [] Identification Indexes (Continued) 



Name 


Value 


Description 


RF DATA 


5 


Data encoding of the data in this resource file. 


Name 


Value 


Meaning 


RE SDATANONE 


0 


Invalid data 


RESDATA2LSB 


i 


Little Endian data encoding 


RESDATA2MSB 


2 


Big Endian data encoding 


RF_VERSION 


6 


Resource file version. 


Name 


Value 


Meaning 


RV_NONE 


0 


Invalid version 


RV_CURRENT 


i 


Current version. The value of 
rv current will change as 
necessary to reflect the 
current version. 


RF_PAD 


7 


Start of padding bytes. These bytes are reserved and set to 
zero. The value of rf pad will change if currently unused 
bytes take on meaning. 



8.1.3 Resource File PowerPC Processor-specific Information 

This section documents the Resource File information specific to the PowerPC processor. 
The rf_ident member shall contain the following identification values. 



Table 8-2: Resource File Identification, rf ident 



Position 


Value 


Meaning 


rf_ident [RF_CLASS] 


RESCLASS32 


32-bit implementation 


rf_ident [RF_DATA] 


RESDATA2LSB 


Little Endian implementation 
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8.2 Resource Collection 

A resource collection is a collection of individual resource items each identified by a unique 
type and ordinal pair with an optional name (unique within type). 

Resource collections are self-contained. All information about the individual resource items 
are contained within the resource collection. All offsets within a resource collection must be 
relative to the start of the resource collection. A resource collection includes the resource 
collection header, the locale information, the resource item array, the resource collection 
string table and all the resource data. 

8.2.1 Resource Header 

A resource collection begins with a resource header. 

Figure 8-3: Resource Header, Res3 2_Hdr 



typedef struct 
{ 

Elf 32_Half 
Elf 32_Half 
Elf 32_Of f 
Elf 32_Of f 
Elf 32_Word 
Elf 32_Word 
Elf 32_Word 
Elf 32_Of f 
Elf 32_Of f 
} Res3 2_Hdr; 



rh_version; 
rh_f lags ; 
rh_name ; 
rh_riof f ; 
rh_rientsize ; 
rh_rinum; 
rh_rhsize ; 
rh_strtab ; 
rh locale; 



Member 



Description 



rh version 



This member holds the resource collection version. The 
current version is l. 



rh_f lags 



This member holds the resource collection flags. There are 
currently no flags defined. 



rh name 



This member specifies the name of the resource collection. Its 
value is an index into the resource string table. See 

rh strtab below. 



rh rioff 



This member holds the offset of the resource item array. The 
offset is relative to the start of the resource collection and shall 
be word aligned. There are rh_rinum entries in the array. See 
§ 8.3, "Resource Item", on page 83 for details on resource 
items. 



rh rientsize 



This member holds the size, in bytes, of a resource item array 
entry. 



rh rinum 



This member holds the number of resources in the collection. 



Release 1 



81 



OS/2 Application Binary Interface for PowerPC (32-bit) 



Figure 8-3: Resource Header, Res32_Hdr (Continued) 



rh rhsize 


This member holds the resource header's size in bytes. 


rh strtab 


This member holds the offset of the resource string table. The 
offset is relative to the start of the resource collection. The 
format of the string table is identical to that of a standard ELF 
string table. The resource string table shall be located at the 
end of the resource collection. 


rh locale 


This member holds the offset of the locale information. The 
offset is relative to the start of the resource collection and shall 
be word aligned. The locale information, if present, shall 
immediately follow the resource header. The locale information 
is detailed below. 



A resource collection may contain resources specific to certain locale. In this case the 
rh_locale member of the resource collection header will hold the offset of the information 
identifying the locale to which the resource collection applies. If the resource collection is not 
locale specific, then the rh_locale member holds zero indicating no specific locale. The 
resource collection locale information is detailed below. 



Figure 8-4: Resource Collection Locale Information, Res32_Locale 



typedef struct 
{ 

Elf32_Half rl_country [2] ; 
Elf32_Half rl_language [2] ; 
} Res32 Locale; 


Member 


Description 


rl country 


This member holds the two character UNICODE 
representation of the country. 


rl language 


This member holds the two character UNICODE 
representation of the language. 
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8.3 Resource Item 



A resource collection contains an array of resource items, with one resource item for each 
resource in the collection. A resource item describes the resource and provides a pointer to 
it's data. 



Figure 8-5: Resource Item, Res32_item 



typedef struct 
{ 

Elf 32 Word ri type; 
Elf 32 Word ri ordinal; 
Elf 32 Off ri name; 
Elf32_Off ri_data; 
Elf32 Word ri size; 
} Res 3 2 Item; 


Member 


Description 


ri type 


This member holds the type of the resource. Its value is 
operating system-specific. The resource type defines the 
meaning of the resource data. 


ri ordinal 


This member holds the ordinal number of the resource. Each 
resource has a unique ordinal within its resource type. 


ri name 


This member specifies the name of the resource ordinal. Its 
value is an index into the resource string table. Names are 
optional for resources. If the resource has no name, this 
member holds the value zero. 


ri data 


This member holds the offset of the resource data. The offset 
is relative to the start of the resource collection and shall be 
word aligned. The format of the resource data is operating 
system-specific. 


ri size 


This member holds the size of the resource data in bytes. 



The resource items shall be sorted by ri_type in ascending order. Within each ri_type 
they shall be further sorted by ri_ordinal in ascending order. This allows for a resource 
(type, ordinal) pair to be located via binary search. 
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9 Object and Load Module File Format 

This chapter describes the formats of the object files and load module files (including 
executables and dynamic link libraries) and debugging information for operating systems and 
development tools conforming to this ABI. 

An object file (et_rel) is the output of a language translator that is suitable for linking with 
other object files to create a load module. A load module is either an executable or a 
dynamic link library (also known as a shared library) and is suitable for loading into a process 
for execution. An executable (et_exec) is a load module that is the basis for the creation of 
a process. It can be dynamically linked with zero or more dynamic link libraries (et_dyn) by 
the system to complete the process image. 
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9.1 ELF 

The format of the object and load module files is based upon the ELF specification, version 
1 . The reader is referred to the Tool Interface Standards Portable Formats Specification and 
Executable and Linking Format (ELF) for a general specification of the ELF format. (See also 
chapters 4 and 5 of System V Application Binary Interface.) Book I of Executable and Linking 
Format (ELF) along with the information in this section describe ELF as required to support 
this ABI. 

9.1.1 ELF Operating System-specific Information 

This section documents the non-processor-specific ELF information required for operating 
systems based upon this ABI. For PowerPC processor-specific information, see § 9.1.2, 
"ELF PowerPC Processor-specific Information", on page 104. 

9.1.1.1 Sections 

The following section types are defined. 



Table 9-1 : Section Types, sh type 



Name 


Value 


Meaning 


SHT_SYMTAB 
SHT_DYNSYM 


2 
11 


These sections hold a symbol table. See "Symbol 
Table" in Executable and Linking Format (ELF), Book 
I for details. A file may have only one section of each 
type. Typically, sht symtab provides symbols for 
static linking. As a complete symbol table, it may be 
used for dynamic linking even though it may contain 
many symbols unnecessary for dynamic linking. A 
load module may also contain a sht dynsym 
symbol table which holds a minimal set of symbols 
necessary for dynamic linking. 


SHT_STRTAB 


3 


This section holds a string table. See "String Table" 
in Executable and Linking Format (ELF), Book I for 
details. A file may have multiple string tables. 


SHT_OS 


0x60000001 


This section holds the information to identify the 
target operating system environment. See § 9.1 .1 .3, 
"Operating System Information", on page 91 for 
details. 


SHT_IMPORTS 


0x60000002 


This section holds information on references to 
external symbols. See § 9.1 .1 .4, "Import Table", on 
page 92 for details. 


SHT_EXPORTS 


0x60000003 


This section holds information on symbols that are 
being exported. See § 9.1 .1 .5, "Export Table", on 
page 94 for details. 
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Table 9-1 : Section Types, sh type (Continued) 



Name 


Value 


Meaning 


SHT_RES 


0x60000004 


This section holds read-only resource data. See 
§ 9.1 .1 .6, "Resource Collection", on page 95 for 
details. 



The following section attribute flags are defined. 



Table 9-2: Section Attribute Flags, sh_f lags 



Name 


Value 


Meaning 


SHF_BEGIN 


0x01000000 


This section shall be placed at the beginning of the 
combination of like-named sections during the static link 
step. Only one of the like-named sections in the 
combination may have the shf begin flag. A section 
may not have both the shf begin and shf end flag. 


SHF_END 


0x02000000 


This section shall be placed at the end of the combination 
of like-named sections during the static link step. Only 
one of the like-named sections in the combination may 
have the shf end flag. A section may not have both the 
shf_begin and shf_end flag. 



These flags are used to control the combination by the static linker of sections having the 
same name when it may be necessary to have a specific section from one object file placed 
at the beginning or end of the combined section in the load module. 



Two members in the section header, sh_link and sh_inf o, hold special information 
depending on the section type. 



Table 9-3: sh link and sh inf o Interpretation 



sh type 


sh link 


sh Info 


SHT_SYMTAB 
SHT_DYNSYM 


The section header index of 
the string table used by 
entries in this section. 


The symbol table index of 
the last local symbol 
(binding stb_local) + 1. 


SHT_OS 
SHT_RES 


SHN_UNDEF 


0 


SHT_IMPORTS 


The section header index of 
the string table used by 
entries in this section. 


0 


SHT_EXPORTS 


The section header index of 
the symbol table used by 
entries in this section. 


The section header index of 
the string table used by 
entries in this section. 
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All these sections must be word aligned. Thus the sh_addralign value for all these 
sections is 4. 

9.1.1.1.1 Special Sections 

The following sections are used by the system and have the indicated types and attributes. 
They are described below. 



Table 9-4: Special Sections 



Name 


Type 


Attributes 


. dynstr 


SHT_STRTAB 


SHF_ALLOC 


. dynsym 


SHT_DYNSYM 


SHF_ALLOC 


. relaname 


SHT_RELA 


see below 


. osinf o 


SHT_OS 


none 


. imports 


SHT_IMPORTS 


SHF_ALLOC 


. exports 


SHT_EXPORTS 


SHF_ALLOC 


. res 


SHT_RES 


none 


Table 9-5: Special Section Descriptions 


Name 


Descriptions 


. dynstr 


This section holds strings used in dynamic linking. 


. dynsym 


This section holds symbols used in dynamic linking. 


. relaname 


These sections hold relocation table entries. See § 9.1.2.3, 
"Relocation", on page 106 for more information. In object files, these 
sections have no attribute flags. In load modules, these sections have 
the shf alloc attribute flag if the section relocates information in a 
pt load segment; otherwise the section has no attribute flags. 
Conventionally, name is supplied by the section to which the 
relocations apply. Thus a relocation section for . text normally would 
have the name . rela . text. 


. osinf o 


This section holds the information to identify the target operating 
system environment. See § 9.1 .1 .3, "Operating System Information", 
on page 91 for details. 


. imports 


The default name of the import table section. This section holds 
information on references to external symbols. See § 9.1 .1 .4, "Import 
Table", on page 92 for details. 
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Table 9-5: Special Section Descriptions (Continued) 



Name 


Descriptions 


. exports 


The default name of the export table section. This section holds 
information on symbols that are being exported. See § 9.1 .1 .5, "Export 
Table", on page 94 for details. 


. res 


The default name of the resource section. This section holds read-only 
resource data. See § 9.1.1.6, "Resource Collection", on page 95 for 
details. 



9.1.1.2 Symbol Table 

The following symbol bindings are defined. 



Table 9-6: Symbol Binding, elf32_st_bind 



Name 


Value 


Meaning 


STB_ENTRY 


12 


This symbol defines an entry point for the load module. This 
symbol binding is only found in object files and provides a 
default entry point to the static linker. Only one symbol with 
this binding may be encountered during static linking. 
Otherwise treated the same as stb global. 



The following symbol types are defined. 



Table 9-7: Symbol Type, elf3 2_st_type 



Name 


Value 


Meaning 


STT_IMPORT 


ii 


This symbol is a reference to a symbol in another load 
module {i.e. this symbol is imported). The st value 
member holds the offset of the import table entry for this 
symbol. Otherwise treated the same as stt func. 



9.1.1.2.1 Symbol Values 

References to symbols defined outside of a load module are resolved using one of two 
techniques. How a load module has been built determines which of these techniques must 
be used for all references to symbols defined in other load modules. 



1 . If the load module's Dynamic segment has a dt_import entry, then all references to 
symbols defined in other load modules will be through the load module's import table. 
The symbol table entry referencing a symbol in another load module will have a type of 
stt_import and the st_shndx member will contain the section header table index of 
the import table section. The st_value member will hold the virtual address of the 
import table entry for the symbol. The import table entry will contain information about 
the load module where the symbol is defined. See § 9.1.1.4, "Import Table", on page 92 
for details on the import table. 
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2. If the load module's Dynamic segment does not have a dt_import entry, then the load 
module does not have a import table. The st_shndx member of the symbol table entry 
referencing a symbol in another load module will contain shn_undef indicating that the 
symbol is defined in another load module. To locate where the symbol is defined, the 
load modules specified by the dt_needed entries in the Dynamic segment must be 
searched. They are searched in the order specified by the ordering of the dt_needed 
entries. Only those load modules specified by the dt_needed entries are searched. If a 
Procedure Linkage Table entry exists in the load module for the symbol, the symbol table 
entry's st_value member shall contain the virtual address of the PLT entry. Otherwise 
the st value member shall contain zero. 



System V ABI Note: In System V Application Binary Interface, a breadth-first search of all 
the dt_needed entries, beginning with the executable, is performed to locate the 
symbol. See "Shared Object Dependencies", System V Application Binary Interface, for 
details. This ABI differs from System V Application Binary Interface by only searching the 
dt_needed entries specified by the load module rather than the entire dt_needed tree 
of the process. 



When searching a load module to resolve a symbol reference from another load module, the 
symbol can be located in one of two ways. How a load module has been built determines 
which of these techniques must be used when searching a load module for a symbol. 

1 . If the load module's Dynamic segment has a dt_export entry, then all symbols 
available to resolve references from other load modules will be located through the load 
module's export table. If the reference is from an import table entry with an ordinal 
number, then a binary search can be performed on the export table entries to locate the 
export table entry with a matching ordinal number. Otherwise if the reference is from an 
import table entry with a name or a symbol table entry whose st_shndx member 
contains shn_undef, the export table entries can be searched to locate the export table 
entry with a matching name. See § 9.1.1.5, "Export Table", on page 94 for details on the 
export table. 

2. If the load module's Dynamic segment does not have a dt_export entry, then the load 
module does not have an export table. All symbols available to resolve references from 
other load modules will be located in the load module's dynamic symbol table 
(dt_symtab). References from an import table entry with only an ordinal number and no 
name cannot be resolved since there is no ordinal information in the dynamic symbol 
table. If the reference is from an import table entry with a name or a symbol table entry 
whose st_shndx member contains shn_undef, the dynamic symbol table can be 
searched, via the symbol hash table (dt_hash), to locate the symbol table entry with a 
matching name. 

Note: All OS/2 load modules (eos_os2) shall be built with import and export tables to 
perform inter-load module symbol resolution. 
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9.1.1.3 Operating System Information 

Multiple operating system environments will be using the ELF format for their objects and 
load modules. In order to identify the target operating environment for these files, an 
operating system information section is used to contain this information. 

All object and load module files shall contain operating system information. The Elf 32_Os 
structure must be present and may be followed by additional operating system-specific 
information. The presence and structure of the operating system-specific information is 
defined by the target operating environment. 



Figure 9-1: Operating System Information, Elf32_Os 



typedef struct 
{ 

Elf32 Word os type; 
Elf 32 Word os size; 
} Elf32_Os; 


Member 


Description 


os type 


This member identifies the target operating system type of the 
file. See Table 9-8, "Operating System Types, os_type", below 
for valid types. 


os size 


Size of the operating system-specific information immediately 
following this structure. This field shall be set to 0 if no 
operating system-specific information follows. 



The following table defines possible values for os_type and their meanings. 



Table 9-8: Operating System Types, os type 



Name 


Value 


Meaning 


EOS_NONE 


0 


Bad or unknown operating system 


EOS_PN 


i 


IBM Microkernel personality neutral 


EOS_SVR4 


2 


UNIX System V Release 4 operating system environment 


EOS_AIX 


3 


IBM AIX operating system environment 


EOS_OS2 


4 


IBM OS/2 operating system, 32 bit environment 
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9.1.1.3.1 OS/2-specific Information 

The Elf 32_0S2info structure shall follow the Elf 32_Os structure in the pt_os segment 
for all OS/2 load modules (os_type equal to eos_os2). OS/2 object files shall only contain 
the Elf 32 Os structure in the sht os section. 



Figure 9-2: OS/2 Information, Elf 32_0S2inf o 



typedef struct 
{ 

unsigned char os2 sessiontype; 
unsigned char os2 sessionf lags ; 
unsigned char os2 reserved [14] ; 
} Elf 32_OS2Info; 


Member 


Description 


os2 sessiontype 


This member holds the OS/2 session type for the load module. 
See Table 9-9, "OS/2 Session Types, os2_sessiontype", below 
for valid types. 


os2 sessionflags 


This member holds the OS/2 session flags for the load 
module. There are no flags currently defined, so this member 
shall be set to zero. 


os2 reserved 


This member is reserved and shall be set to zero. 



The following table defines possible values for os2_sessiontype and their meanings. 



Table 9-9: OS/2 Session Types, os2_sessiontype 



Name 


Value 


Meaning 


OS2_SES_NONE 


0 


No session type. This value is the only valid value for 
dynamic link libraries. This value is invalid for executables. 


OS2_SES_FS 


i 


Full Screen session. 


OS2_SES_PM 


2 


Presentation Manager session. 


OS2_SES_VIO 


3 


Windowed (character-mode) session. 



9.1.1.4 Import Table 

An import table holds information on references to external entry points that must be 
resolved when a load module is dynamically linked into a process image. These entry points 
are symbols exported by other load modules. An exported entry point can be imported by 
name or by ordinal. Import by ordinal is preferred since the ordinal can be quickly located in 
the export table of the entry point exporter. Import by name involves searching for the name 
of the entry point in the export table of the entry point exporter. 

An import table is an array of import table entries. The entries in the table have no sorting 
requirements. All import tables entries are referenced by symbol table entries. Import tables 
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can be present in object files and provide information about external entry points to the static 
linker. This information can also be explicitly provided to the static linker via linker directives. 
The static linker will use this information to build the import table in the load module for use 
by the dynamic linker. 

Following is the format of an import table entry. The ordinal values 0 and -1 are reserved. 



Figure 9-3: Import Table Entry, Elf 32_import 



typedef struct 
{ 

Elf 32 Word imp ordinal; 
Elf 32 Word imp name; 
Elf32 Word imp info; 
Elf32 Word imp reserved; 
} Elf 32 Import; 


Member 


Description 


imp ordinal 


This member identifies the ordinal number of the exported 
entry point in the providing load module. Its value may be -1 if 
the exported entry point is referenced by imp name. 
Reference by ordinal takes precedence over reference by 
name. 


imp name 


This member holds a string table index of the exported entry 
point name. Its value may be zero if the exported entry point is 
referenced by imp ordinal. 


imp info 


This member specifies the load module providing the exported 
entry point. It is interpreted as shown below in Figure 9-4, 
"imp_info Description". 


imp reserved 


This member is reserved and set to zero. 



The imp_inf o member holds an index to the name of the load module and describes how 
to interpret the index. The following code shows how to manipulate the value. 

Figure 9-4: imp inf o Description 



#define ELF32_IMP_TYPE ( i ) ((i) >> 24) 
#define ELF32_IMP_DLL ( i ) ((i) & OxOOffffff) 

#define ELF32_IMP_INFO (t , d) (((t) << 24) | ( (d) & OxOOffffff)) 


ELF32IMPTYPE 


ELF3 2_IMP_DLL 


Name 


Value 


Meaning 


IMP_IGNORED 


0 


This import table entry shall be ignored. 


IMP_STR_IDX 


1 


The value is a string table index to the name of the load 
module. This type is used by import tables in object files. 
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Figure 9-4: imp inf o Description (Continued) 



IMP DT IDX 




The value is a reference to a dt_needed entry in the 
Dynamic segment. A value of 1 here refers to the load 
module referenced by the first dt_needed element, a value 
of 2 refers to the second and so forth. The order of the 
dt_needed elements is therefore significant. A value of 0 is 
invalid. This type is used by import tables in load modules. 



9.1.1.5 Export Table 

An export table holds information on exported symbols. Symbols can be exported by name, 
by ordinal or by both name and ordinal. Exported symbols have an export table entry 
associated with them. 



Export tables can be present in object files and provide information to the static linker about 
symbols to be exported by the load module. This information can also be explicitly provided 
to the static linker via linker directives. The static linker will use this information to build the 
export table in the load module for use by the dynamic linker. 

An export table is an array of export table entries. The export table entries are sorted in 
ascending order by ordinal number to facilitate binary searches on the table. Following is the 
format of an export table entry. 



Figure 9-5: Export Table Entry, Elf 32_Export 



typedef struct 
{ 

Elf 32_Word 
Elf 32_Word 
Elf 32_Word 
Elf 32_Word 
} Elf 32 Export; 






exp ordinal ; 
exp symbol ; 
exp name ; 
exp reserved; 


Member 


Description 


exp ordinal 


This member holds the exported ordinal number. Its value may 
be -1 if the symbol is exported only by name. 


exp symbol 


This member holds the symbol table index of the symbol being 
exported. 


exp name 


This member holds the string table index of the exported 
name. Its value may be zero if the symbol is exported only by 
ordinal. 


exp reserved 


This member is reserved and set to zero. 



Note: An executable is not permitted to export symbols. Only dynamic link libraries may 
export symbols. 
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9.1.1.6 Resource Collection 

A resource section (sht_res) or resource segment (pt_res) contains a resource collection 
of the same class and data encoding as the ELF file containing the section or segment. See 
§ 8, "Resource File Format", on page 77 for general information on resources and § 8.2, 
"Resource Collection", on page 81 for the format of a resource collection. 

9.1.1.7 Segments 

When the static linker creates the program header table for a load module, it must ensure 
that the virtual address ranges assigned to pt_load segments are disjoint and are not 
directly adjacent, i.e. there must be one or more bytes of unassigned virtual address space 
between neighboring segments. 

The following segment types are defined. 



Table 9-10: Segment Types, p type 



Name 


Value 


Meaning 


PT_OS 


0x60000001 


This segment holds the information to identify the 
target operating system environment. See § 9.1 .1 .3, 
"Operating System Information", on page 91 for details. 
This segment is required in all load modules. 


PT_RES 


0x60000002 


This segment holds read-only resource data. See 
§ 9.1 .1 .6, "Resource Collection", on page 95 for 
details. For program table header entries of this type, 
p vaddr shall be zero. 



9.1.1.7.1 Segment Permissions 

The following segment permission flags are defined. 



Table 9-11: Segment Permission Flags, p_f lags 



Name 


Value 


Meaning 


PF_X 


0x1 


This segment has execute permission. 


PF_W 


0x2 


This segment has write permission. 


PF_R 


0x4 


This segment has read permission. 


PF_S 


0x01000000 


This segment is shared. The data in this segment is to 
be shared among all processes using this load module. 
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Table 9-11: Segment Permission Flags, p_f l ags (Continued) 



Name 


Value 


Meaning 






Thic con m ont io mannDrl into t ho kornol qHHi-occ cma^Q 
I l Mo ocy 1 1 lul II lo II ld|J|Jc;U II ILU LI It? rxfcM I IfcJI dUU 1 coo opctL-fc?. 

This flag is used to indicate that the dynamic link library 
is a kernel extension and executes at supervisor 
privilege. Kernel extensions are defined to be memory 
resident and need not specify the pf_m flag. 

Note: This flag is valid only for dynamic link libraries. 
If present, this flag must be specified for all 
pt load segments in the load module. 


PF_M 


0x04000000 


This segment is memory resident. This flag is used to 
indicate that the load module is to be memory resident. 

Note: If present, this flag must be specified for all 
pt load segments in the load module. 


PF_MASKPROC 


Oxf 0000000 


There are no processor-specific flags for PowerPC. 



If a permission bit is zero, that type of access is denied. Typical flag combinations appear 
below. 



Table 9-12: Typical Segment Permission Flag Combinations 



Flags 


Meaning 


PF_R PF_X 


Execute/Read (Text segment) 


PF_R PF_W 


Read/Write (Data segment) 


PF_R PF_W PF_S 


Read/Write/Shared (Shared data segment) 



Note: A typical load module normally has two or three pt_load segments. There is 

generally always a text segment (pf_r | pf_x) and a data segment (pf_r | pf_w). 
There may also be a shared data segment (pf_r | pf_w | pf_s). In general, all of the 
code and data for a load module can be allocated into one of these three segments. 



96 



Release 1 



Object and Load Module File Format 

9.1.1.7.2 Segment Contents 

The following table illustrates segment contents and the recommended segment ordering for 
load modules. Some segment types are optional. 



Table 9-13: Segment Ordering 



Segment 


Sections 


PT_OS 

Operating system information 


. osinf o 


PT_INTERP 

Program interpreter 


. interp 


PT_PHDR 

Program header table 




pt load (read/execute) 
Text segment 

Note: Only one executable pt load 
segment is allowed in a load 
module. 


. rodata 
. tags 
. imports 
. exports 

.dynamic (PT DYNAMIC segment) 
. dynsym 
. dynstr 
. nasn 

. rela . rodata 
. rela . got 
. rela . pit 
. rela . data 
. text 
. got 
.pit 


pt load (read/write) 
Data segment 


. data 
. bss 


PT_DYNAMIC 

Dynamic segment 


This program header table entry describes the 
. dynamic section in the Text segment above. 


PT_* 

Segment types not otherwise specified 




PT_RES 

Resource collection 


. res 
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Table 9-13: Segment Ordering (Continued) 



Segment 


Sections 


Other data 


. comment 


This is data that can be stripped from 


. symtab 


the load module without affecting the 


. strtab 


validity of the load module. 


. line 




. debug 




. rela . line 




. rela . debug 




. shstrtab 



• All sht_nobits sections {e.g. . pit and . bss) shall be grouped at the end of their 
respective segments. 

• The .got and .pit sections shall be adjacent with the .got (sht_progbits) section 
immediately preceding the .pit (sht_nobits) section. 

• The presence of segments and sections within segments is variable. The actual order 
and membership of sections within a segment may alter the example above. 

• While, in general, the system is tolerant of deviations from the recommended segment 
ordering, some tools which operate on load modules may not be (e.g. elfstrip which 
removes debugging information from load modules). It is therefore strongly urged that 
the recommended segment ordering be used. 

Note: ELF specifies the following ordering requirements for entries in the Program Header 
table. 

• If a pt_interp entry is present, it must precede all pt_load entries. 

• If a pt_phdr entry is present, it must precede all pt_load entries. Furthermore, the 
pt_phdr segment must be part of the memory image of the load module. This means 
that the area of the load module file containing the Program Header table which is 
mapped by the pt_phdr segment must also be mapped by a pt_load segment. 

• All pt_load entries must appear in ascending order sorted by p_vaddr. 
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9.1.1.8 Dynamic Segment 

All load modules shall contain a Dynamic Segment referenced by a segment type of 
pt_dynamic. This segment contains an array of Elf 3 2_Dyn structures. 



Figure 9-6: Dynamic Structure, Elf 32_Dyn 



typedef struct 
{ 

Elf32 Sword d tag; 

union 

{ 

Elf32_Word d_val; 
Elf32_Addr d_ptr; 
} d un; 
} Elf32_Dyn; 


Member 


Description 


d tag 


This member identifies the array entry. See Table 9-14, 
"Dynamic Array Tags, d_tag" below and Table 9-24, "Dynamic 
Array Tags, d_tag," on page 111 for possible values. The value 
of d tag controls in interpretation of the union d un. 


d val 


This member holds an integer value whose meaning is 
interpreted by the d_tag value. 


d ptr 


This member holds an address whose meaning is interpreted 
by the d_tag value. When interpreting addresses in the 
Dynamic Segment, the dynamic linker computes actual 
addresses, based upon the original file value and the memory 
base address. For consistency, files do not contain relocation 
entries to "correct" addresses in the Dynamic Segment. 



The following dynamic array tags are defined. A "mandatory" tag must be present in the 
Dynamic Segment. An "optional" tag may be present but is not required. An "ignored" tag 
may be present but is not used. An "invalid" tag may not be present in a valid load module. 



Table 9-14: Dynamic Array Tags, d tag 



Name 


Value 


d un 


Executables 


Dynamic 
Link Libraries 


DT_NULL 


0 


ignored 


mandatory 


mandatory 


DT_NEEDED 


i 


d val 


optional 


optional 


DT_HASH 


4 


d ptr 


mandatory 


mandatory 


DT_STRTAB 


5 


d ptr 


mandatory 


mandatory 


DT_SYMTAB 


6 


d ptr 


mandatory 


mandatory 
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Table 9-14: Dynamic Array Tags, d tag (Continued) 



Name 


Value 


d un 


Executables 


Dvnamic 
Link Libraries 


DT_STRSZ 


10 


d val 


mandatory 


mandatory 


DT_SYMENT 


11 


d val 


mandatory 


mandatory 


DT_SONAME 


14 


d val 


ignored 


mandatory 


DT_DEBUG 


21 


d ptr 


optional 


optional 


DT_EXPORT 


0x60000001 


d ptr 


invalid 


optional 


DT_EXPORTSZ 


0x60000002 


d val 


invalid 


optional 


DT_EXPENT 


0x60000003 


d val 


invalid 


optional 


DT_IMPORT 


0x60000004 


d ptr 


optional 


optional 


DT_IMPORTSZ 


0x60000005 


d val 


optional 


optional 


DT_IMPENT 


0x60000006 


d val 


optional 


optional 


DT_IT 


0x60000007 


d val 


invalid 


mandatory 


DT_ITPRTY 


0x60000008 


d val 


invalid 


mandatory 


DT_INITTERM 


0x60000009 


d ptr 


invalid 


mandatory 


DT_S TACKS Z 


0x6000000a 


d val 


optional 


ignored 



The dynamic array tags are described below. 

Table 9-15: Dynamic Array Tag Descriptions 



Name 


Meaning 


DT_NULL 


This entry marks the end of the Dynamic Segment. 


DT_NEEDED 


This element holds the string table index, into the string table referenced 
by dt strtab, of a needed dynamic link library. The ordering of 
dt needed elements is significant. See § 9.1 .1 .2.1 , "Symbol Values", 
on page 89 for additional information. 


DT_HASH 


This entry holds the address of the symbol hash table described in 
§ 9.1.1.10, "Hash Table", on page 103. This hash table refers to the 
symbol table referenced by the dt symtab entry. 


DT_STRTAB 


This entry holds the address of the string table used in dynamic linking. 
Symbol names, library names and other strings reside in this table. 


DT_SYMTAB 


This entry holds the address of the symbol table used in dynamic linking. 
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Table 9-15: Dynamic Array Tag Descriptions (Continued) 



Name 


Meaning 


DT_STRSZ 


This entry holds the size, in bytes, of the string table referenced by 

JJ ± D 1K1 HD . 


DT_SYMENT 


This entry holds the size, in bytes, of a symbol table entry in the symbol 

tahlo r*of oronporl h\/ nT CVMTflD 

IdUIC? 1 t?l t?l t?l IL-t?U Uy JJ 1 O JL l v l 1 fiD . 


DT_SONAME 


This element holds the string table index, into the string table referenced 

h\\/ t^t G T "D i -1 7\ "Q r\f tho n a m o r\f thic Hwnomir* link lihrarw 
Uy JJ 1 olKl/iD, Ul Lllc lldlllt; Ul LI Mo Uyi IcLI 1 ML> Milrx llUldly. 


DT_DEBUG 


This entry is used for debugging. Its contents are not specified by this 

ARI 

nDI. 


DT_EXPORT 


This entry holds the address of the export table, described in § 9.1.1 .5, 

"F Ynnrt Tcihlo" nn nano QA 
la|jui l iduic , uii pdytr yn-. 


DT_EXPORTSZ 


This entry holds the total size, in bytes, of the export table. This entry 

mi lot 3ppnmnan\; cx 'Pit 1 TrviDr^'D r P ontr\/ 
IIIUol dUOUl 1 1 Udi iy d JJ 1 JiAJrUKl cllLly. 


DT_EXPENT 


This entry holds the size, in bytes, of an export table entry. This entry 

1 1 1 Uol dUUUl 1 1 Udl iy dJJl JlArUK.1 fcJllliy. 


DT_IMPORT 


This entry holds the address of the import table, described in § 9.1.1 .4, 
"Import Table", on page 92. 


DT_IMPORTSZ 


This entry holds the total size, in bytes, of the import table. This entry 
must accompany a dt import entry. 


DT_IMPENT 


This entry holds the size, in bytes, of an import table entry. This entry 
must accompany a dt import entry. 


DT_IT 


This entry holds the initialization and termination types for a dynamic link 
library. This entry is mandatory if dt initterm is specified. See 
§ 9.1.1.9, "Initialization and Termination Functions", on page 102 for 
details. 


DT_ITPRTY 


This entry holds a priority value indicating the relative priority of the 
initialization and termination of this dynamic link library to all other 
dynamic link libraries in a process. This entry is mandatory if 
dt initterm is specified. See § 9.1 .1 .9, "Initialization and Termination 
Functions", on page 102 for details. 


DT_INITTERM 


This entry holds the address of the initialization and termination function. 
This function performs both initialization and termination duties. This 
entry will hold zero if there is no initialization and termination function. 
See § 9.1 .1 .9, "Initialization and Termination Functions", on page 1 02 for 
details. 
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Table 9-15: Dynamic Array Tag Descriptions (Continued) 



Name 


Meaning 


DT_STACKSZ 


This entry holds the requested size of the stack for the executable. (This 
is the stack for thread 1 in the process.) The system will create the stack 
with a size greater than or equal to the specified size. If this entry is not 
present, then the system will create the stack with a default size. 



9.1.1.9 Initialization and Termination Functions 



The dt_it entry identifies the type of initialization and termination behavior for an OS/2 
dynamic link library. The following code show how to manipulate its value and its meaning. 



Figure 9-7: dt it Description 



#define ELF32_IT_INIT (it) ((it) & OxOf) 
#define ELF3 2_IT_TERM (it) (((it) >> 4) & OxOf) 

#define ELF32_IT_INFO (i , t) (((i) & 0x0f)|(((t) & OxOf) << 4)) 


ELF3 2 IT INIT and ELF3 2 IT TERM 


Name 


Value 


Meaning 


IT_NONE 


0 


No initialization or termination. The dynamic link library is not 
called for initialization or termination. 


IT_GLOBAL 


l 


Global initialization or termination. If a dynamic link library is 
not in use by any process and a new process causes the 
dynamic link library to be loaded, the initialization routine is 
called. If a process causes a dynamic link library to be 
unloaded and no other process is using the dynamic link 
library, the termination routine is called. 


IT_INSTANCE 


2 


Process initialization or termination. If a process causes a 
dynamic link library to be loaded, the initialization routine is 
called. If a process causes a dynamic link library to be 
unloaded, the termination routine is called. 


IT_THREAD 


3 


Note: This value is currently not supported but is reserved 
for future use. 



The remaining values are reserved. If initialization or termination is indicated then the 
dt_initterm entry must be present and non-zero. The dt_itprty entry holds a priority 
value that, when compared with the dt_itprty values of the other dynamic link libraries in 
a process image, gives a relative ordering of the initialization and termination of the dynamic 
link libraries in the process image. A value of zero is the highest priority with priority 
decreasing as the value increases. The order in which dynamic link libraries with the same 
priority value are initialized and terminated is unspecified. 
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The initialization and termination function, whose address is specified by dt_initterm, is 
called with two parameters as described below. 



Figure 9-8: dt initterm Function Prototype 



typedef unsigned long INITTERM ( unsigned long modhandle, 

unsigned long flag ) ; 


Parameter 


Description 


modhandle 


This parameter holds a system assigned handle for the load 
module. 


flag 


This parameter holds one of the following values. 


0 


If the entry point is being called for initialization. 


1 


If the entry point is being called for termination. 


Return Value 


A non-zero return value indicates successful initialization/ 
termination. A zero return value indicates that initialization/ 
termination failed. If a failure is indicated, the system will abort 
the load of the dynamic link library. If this failure occurs during 
process start-up, the system will abort the process. 



See § 11.2, "Process Initialization", on page 131 and § 11.3, "Process Termination", on page 
133 for more information on dynamic link library initialization and termination. 



9.1.1.10 Hash Table 

A hash table of Elf 32_Word entries supports symbol table access. Labels appear below to 
help explain the hash table organization, but they are not part of the specification. 

Figure 9-9: Symbol Hash Table 

nbucket 
nchain 
bucket [0] 

bucket [nbucket -1] 
chain [0] 

chain [nchain- 1] 

The bucket array contains nbucket entries and the chain array contains nchain entries. 
Both indexes start at zero. Both bucket and chain hold symbol table indexes. Chain table 
entries parallel the symbol table. The number of symbol table entries should equal nchain; 
so symbol table indexes also select chain table entries. A hashing function accepts a symbol 
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name and returns a value that may be used to compute a bucket index. Consequently, if 
the hashing function returns the value xfor some name, bucket [x%nbucket] gives and 
index, y into both the symbol table and the chain table. If the symbol table entry is not the 
one desired, chain [y] gives the next symbol entry with the same hash value. One can 
follow the chain links until either the selected symbol entry holds the desired name or the 
chain entry contains the value stn_undef. 

Figure 9-10: Hashing Function 



unsigned long elf_hash ( const unsigned char * name ) 
{ 

unsigned long h = 0, g; 

while ( *name ) 
{ 

h = ( h << 4 ) + *name++; 
if ( g = h & OxfOOOOOOO ) 

h A = g >> 24; 
h &= ~g; 

} 

} 



9.1 .2 ELF PowerPC Processor-specific Information 

This section documents the ELF information specific to the PowerPC processor. 

9.1.2.1 ELF Header 

9.1.2.1.1 Machine Identification 

The e_ident member shall contain the following identification values. 



Table 9-16: ELF Identification, e ident 



Position 


Value 


Meaning 


e_ident [EI_CLASS] 


ELFCLASS32 


32-bit implementation 


e_ident [EI_DATA] 


ELFDATA2LSB 


Little Endian implementation 



The e_machine member shall contain the following machine type. 



Table 9-17: Processor Identification, e machine 



Name 


Value 


Meaning 


EM_PPC 


20 


PowerPC Architecture 
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The e_f lags member may contain a combination of the following processor-specific flags. 

Table 9-18: Processor Flags, e_f lags 



Name 


Value 


Meaning 


EF_PPC_EMB 


0x80000000 


Reserved for use in embedded systems. 



9.1.2.2 Sections 
9.1.2.2.1 Special Sections 

The following sections are used by the system and have the indicated types and attributes. 
They are described below. 

Table 9-19: Special Sections 



Name 


Type 


Attributes 


. got 


SHT_PROGBITS 


SHF_ALLOC SHF_EXECINSTR 


.pit 


SHT_NOBITS 


SHF_ALLOC SHF_EXECINSTR 


. tags 


SHT_PROGBITS 


SHF_ALLOC 



Table 9-20: Special Section Descriptions 



Name 


Descriptions 


. got 


This section holds the Global Offset Table or GOT. See § 11 .5, "Global 
Offset Table (GOT)", on page 135 for details. 


.pit 


This section holds the Procedure Linkage Table or PLT See § 11 .6, 
"Procedure Linkage Table (PLT)", on page 137 for details. 

Note: The .pit section on PowerPC is of type sht nobits, not 
sht progbits as on most other processors. 


. tags 


This optional section holds the long form function tag information. See 
§ 7.2, "Function Tags", on page 58 for details on function tags. 



System V ABI Note: The System V Application Binary Interface, PowerPC Processor 
Supplement defines both the .got and .pit sections to have the shf_write attribute. 
It additionally does not define the .got section to have the shf_execinstr attribute. 



Note: The section names . sdata and . sbss are assigned for use by UNIX System V. 
Section names beginning with . ppc . emb . and the section name . rosdata are 
assigned for use by embedded systems. 
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System V ABI Note: The System V Application Binary Interface, PowerPC Processor 
Supplement defines a Small Data Area with initialized data in section . sdata and 
uninitialized data in section . sbss. 



9.1.2.3 Relocation 

This ABI specifies the use of only relocation entries with explicit addends, i.e. Elf 32_Rela. 
Relocations are applied to halfwords or words and the r_of f set field holds the offset or 
virtual address of the storage unit to be modified. The r_addend member holds the 
relocation addend. All values use the data encoding specified in the ELF header. 

9.1.2.3.1 Relocation Types 

The relocation types specify how to compute the relocation value and which bits to modify in 
the target storage unit. 



The following relocation fields are defined. Little Endian byte numbers are in the upper 
corners. Bit numbers appear in the lower corners. 

Table 9-21 : Relocation Fields 



Field 



Description 



word32 



Specifies a 4 byte field with word 
alignment. 



word32 



31 



low24 



3 






low24 




0 


0 


5 


6 




29 


31 



Specifies a 24-bit field contained within an 
aligned word. The 24-bit relative 
displacement in bits 6-29 are modified 
and the remaining bits are ignored and 
unmodified. (See the LI field of the I 
Instruction Format in PowerPC 
Architecture.) 



lowl4 



3 






low14 




0 


0 


15 


16 




29 


31 



Specifies a 14-bit field contained within an 
aligned word. The 14-bit relative 
displacement in bits 16-29 are modified 
and bit 10 (branch prediction) may be 
modified depending on the relocation 
type. The remaining bits are ignored and 
unmodified. (See the BC>4and BD fields of 
the B Instruction Format in PowerPC 
Architecture.) 
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Table 9-21 : Relocation Fields (Continued) 



Field 



Description 



half 16 



1 




0 




half 16 




0 




15 



Specifies a 2 byte field with halfword 
alignment. (See the D, SI or Ul fields of 
the D Instruction Format in PowerPC 
Architecture.) 



The following variables are defined for use in the relocation calculations. 

Table 9-22: Relocation Variables 



Variable 


Definition 


A 


Addend to be used in the relocation calculation. The r addend member of 
the relocation entry holds this value. 


B 


Adjustment to the base address of a segment. When the load module is 
created by the static linker, each segment is created with a base address. 
This is specified by the p vaddr member of the program header table entry 
for the segment. The difference between the actual load address for the 
segment and the address specified in p vaddr is the value of b. Each 
segment will have its own, possibly unique, value of b. When using the 
variable b in a relocation calculation (for r ppc relative), the value being 
relocated must be examined to determine which segment it references. The 
value of b used in the calculation will be the value of b corresponding to the 
referenced segment. 


G 


Offset in the Global Offset Table (from the symbol 

global offset table ) of the GOT entry which will contain the address 
of the relocation entry's symbol. See § 11 .5, "Global Offset Table (GOT)", on 
page 135 for more information. 


L 


Section offset or virtual address of the Procedure Linkage Table entry of the 
relocation entry's symbol. See § 11.6, "Procedure Linkage Table (PLT)", on 
page 137 for more information. 


P 


Section offset or virtual address of the storage unit being relocated. The 
r offset member of the relocation entry holds this value. 


S 


Value of the relocation entry's symbol. The st value member of the symbol 
table entry referenced by the relocation entry holds this value. 



Section offsets are used in object files and virtual addresses are used in load modules. 

The following general rules apply to the interpretation of the relocation types in Table 9-23, 
"Relocation Types". 
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• The value of the calculation replaces the value in the field being relocated. In no case 
does the value in the field participate in the calculation. 

• "+" and "-" denote 32-bit modulus addition and subtraction, respectively, of the left and 
right operands. ">>" denotes arithmetic right shifting (shift with sign copy) of the left 
operand by the number of bits specified by the right operand. 

• @l (value) returns the least significant 16-bits of the 32-bit value. @h (value) returns the 
most significant 16-bits of the 32-bit value. @ha (value) returns the most significant 16- 
bits of the 32-bit value adjusted for @l (value) being treated as a signed number. 

• @1 (X) = (X & OxFFFF) 

• @h(X) = ( (X >> 16) & OxFFFF) 

• @ha(X) = (((X >> 16) + ( (X & 0x8000) ? 1 : 0)) & OxFFFF) 

• References to the variable G in the calculation implicitly directs the static linker to create 
a GOT entry for the referenced symbol. 

• References to the variable L in the calculation implicitly directs the static linker to create 
a PLT entry for the referenced symbol. 

• The static linker shall report all relocation failures as errors. 



Table 9-23: Relocation Types 



Name 


Value 


Field 


Calculation 


Notes 


R_PPC_NONE 


0 


none 


none 


5 


R_PPC_ADDR32 


i 


word32 


S + A 


5 


R_PPC_ADDR24 


2 


low24 


(S + A) >> 2 


1,2,4 


R_PPC_ADDR16 


3 


half 16 


S + A 


1,3 


R_PPC_ADDR16_LO 


4 


half 16 


Ol (S + A) 




R_PPC_ADDR16_HI 


5 


half 16 


@h(S + A) 




R_PPC_ADDR16_HA 


6 


half 16 


@ha(S + A) 




R_PPC_ADDR14 


7 


lowl4 


(S + A) >> 2 


1,3,4 


R_PPC_ADDR14_BRTAKEN 


8 


lowl4 


(S + A) >> 2 


1,3,4,7 


R_PPC_ADDR14_BRNTAKEN 


9 


lowl4 


(S + A) >> 2 


1,3,4,7 


R_PPC_REL24 


10 


low24 


(S + A - P) >> 2 


1,2,4 


R_PPC_REL14 


11 


lowl4 


(S + A - P) >> 2 


1,3,4 


R_PPC_REL14_BRTAKEN 


12 


lowl4 


(S + A - P) >> 2 


1,3,4,7 


R_PPC_REL14_BRNTAKEN 


13 


lowl4 


(S + A - P) >> 2 


1,3,4,7 


R_PPC_GOT16 


14 


half 16 


G + A 


1,3,6 
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Table 9-23: Relocation Types (Continued) 



Name 


Value 


Field 


Calculation 


Notes 


R_PPC_GOT16_LO 


15 


half 16 


ml (g + a) 


6 


R_PPC_GOT16_HI 


16 


half 16 


@h(G + A) 


6 


R_PPC_GOT16_HA 


17 


half 16 


@ha(G + A) 


6 


R_PPC_PLTREL24 


18 


low24 


(L + A - P) >> 2 


1,2,4,8 


R_PPC_COPY 


19 


none 


see note 9 


5,9 


R_PPC_GLOB_DAT 


20 


word32 


S + A 


5,10 


R_PPC_JMP_SLOT 


21 


none 


see note 11 


5,11 


R_PPC_RELATIVE 


22 


word32 


B + A 


5,12 


R_PPC_LOCAL24PC 


23 


low24 


see note 13 


1,2,4,13 


R_PPC_UADDR32 


24 


word32 


S + A 


14 


R_PPC_UADDR16 


25 


half 16 


S + A 


1,3,14 


R_PPC_REL32 


26 


word32 


S + A - P 




R_PPC_PLT32 


27 


word32 


L + A 


8 


R_PPC_PLTREL32 


28 


word32 


L + A - P 


8 


R_PPC_PLT16_LO 


29 


half 16 


©1 (L + A) 


8 


R_PPC_PLT16_HI 


30 


half 16 


@h(L + A) 


8 


R_PPC_PLT16_HA 


31 


half 16 


@ha(L + A) 


8 


R_PPC_SDAREL16 


32 


half 16 


see note 9 


1,3,9 


R_PPC_SECTOFF 


33 


half 16 


see note 9 


1,3,9 


R_PPC_SECTOFF_LO 


34 


half 16 


see note 9 


9 


R_PPC_SECTOFF_HI 


35 


half 16 


see note 9 


9 


R_PPC_SECTOFF_HA 


36 


half 16 


see note 9 


9 


R_PPC_REL3 0 


37 




see note 9 


9 



The entries in the Notes column are defined below. 



1 . The relocation is subject to failure if the computed value does not fit within the bits 
specified by the Field column. 

2. The most significant 7 bits of the computed value, before any shifting, must all be the 
same. 
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3. The most significant 1 7 bits of the computed value, before any shifting, must all be 
the same. 

4. The least significant 2 bits of the computed value, before any shifting, must be zero. 

5. This relocation type may be seen by the dynamic linker 

6. This relocation type directs the static linker to build a Global Offset Table and to add 
a GOT entry to the table which will contain the address of the relocation entry's 
referenced symbol. There will be only one GOT entry for each symbol. 

7. This relocation type indicates that the branch prediction bit (bit 1 0) of the conditional 
branch instruction being relocated should be modified. The _brtaken suffix predicts 
the branch will be taken. The _brntaken suffix predicts the branch will not be taken. 

8. This relocation type directs the static linker to build a Procedure Linkage Table and 
to add a PLT entry to the table for the relocation entry's referenced symbol. There 
will be only one PLT entry for each symbol. Since the PLT entry is assumed to be ± 
32MB from the call site, the r_ppc_pltrel24 relocation type is the only type 
needed to relocate branches to PLT entries. 

9. This relocation type is not used in this ABI but is assigned for use by UNIX System V. 

10. This relocation type is used to set a Global Offset Table entry to the address of the 
specified symbol. It is otherwise identical to r_ppc_addr32 but allows a 
correspondence between symbols and GOT entries to be determined. 

11 . This relocation type directs the dynamic linker to relocate Procedure Linkage Table 
entries. The dt_jmprel entry in the Dynamic segment points to an array of these 
relocation entries. There is a one-to-one correspondence between the relocation 
entries and the PLT entries. See § 11.6, "Procedure Linkage Table (PLT)", on page 
1 37 for additional details. 

12. This relocation type directs the dynamic linker to perform a relative relocation. The 
r_addend member holds a pointer to which the relative relocation is to be applied. 
The pointer was initialized by the static linker based upon the p_vaddr member of 
the program header table entry for the segment into which the pointer points. The 
pointer must be relocated based upon the load address of that segment. The pointer 
is adjusted by the difference between the actual load address and the p_vaddr 
address of the segment into which the pointer points (the relocation variable b). The 
storage unit addressed by r_of f set is then assigned the adjusted pointer. This 
relocation type shall specify no symbol, i.e. the symbol table index shall be zero. 

The static linker shall also store the pointer to which the relative relocation is to be 
applied in the storage unit addressed by r_of f set as well as in the r_addend 
member. This will allow the dynamic linker to avoid processing r_ppc_relative 
relocations if all the segments are loaded at the virtual addresses specified by their 
respective p_vaddr members since the storage units will already contain the correct 
value (because the relocation variable b will be zero for all segments in the load 
module). 

1 3. This relocation type uses the value of the symbol from the individual object file rather 
than the adjusted symbol value after combining all objects. It is otherwise identical to 
r_ppc_rel24. The referenced symbol for this relocation type is normally 
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_global_offset_table_, which additionally directs the static linker to build a 
Global Offset Table. 

14. This relocation type allows the relocated storage unit to be unaligned. 

Relocation values in the range 101-200 and names beginning with r_ppc_emb_ are 
assigned for embedded system use. All relocation values not listed in Table 9-23, "Relocation 
Types", or otherwise assigned are reserved. 

System V ABI Note: The System V Application Binary Interface, PowerPC Processor 
Supplement defines the relocation types r_ppc_copy, r_ppc_sdareli6 and 
r_ppc_sectoff*. These relocation types are not supported by this ABI. 

9.1.2.4 Dynamic Segment 

The following processor-specific dynamic array tags are defined. A "mandatory" tag must be 
present in the Dynamic Segment. An "optional" tag may be present but is not required. 



Table 9-24: Dynamic Array Tags, d tag 



Name 


Value 


d un 


Executables 


Dynamic 
Link Libraries 


DT_PLTRELSZ 


2 


d val 


optional 


optional 


DT_PPC_PLT 
DT_PLTGOT 


3 


d ptr 


optional 


optional 


DT_RELA 


7 


d ptr 


mandatory 


mandatory 


DT_RELASZ 


8 


d val 


mandatory 


mandatory 


DT_RELAENT 


9 


d val 


mandatory 


mandatory 


DT_PLTREL 


20 


d val 


optional 


optional 


DT_JMPREL 


23 


d ptr 


optional 


optional 


DT_PPC_GOT 


0x70000001 


d ptr 


optional 


optional 


DT_PPC_GOTSZ 


0x70000002 


d val 


optional 


optional 


DT_PPC_PLTSZ 


0x70000003 


d val 


optional 


optional 
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The dynamic array tags are described below. 



Table 9-25: Dynamic Array Tag Descriptions 



Name 


Meaning 


DT_PLTRELSZ 


This entry holds the total size, in bytes, of the relocation entries 
associated with the Procedure Linkage Table. This entry must 
accompany a dt jmprel entry. 


DT_PPC_PLT 
DT_PLTGOT 


This entry holds the address of the Procedure Linkage Table, i.e. the 
address of the .pit section. For additional information on the 
Procedure Linkage Table, see § 11 .6, "Procedure Linkage Table (PLT)", 
on page 137. 


DT_RELA 


This entry holds the address of the relocation table. This relocation 
table holds all relocation entries except those for the Procedure 
Linkage Table. They are contained in the relocation table addressed by 

DT_JMPREL. 

The relocation entries in this table shall be sorted by r offset values 
in ascending order. This will allow the dynamic linker to easily locate all 
relocations for given memory page. 

Note: Since only relocation entries with explicit addends are specified 
in this ABI, all relocation entries are of the form Elf 32 Rela. 


DT_RELASZ 


This entry holds the total size, in bytes, of the relocation table 
referenced by dt rela. This entry must accompany a dt rela entry. 


DT_RELAENT 


This entry holds the size, in bytes, of a relocation table entry in the 
relocation table referenced by dt rela. This entry must accompany a 
dt rela entry. 


DT_PLTREL 


This entry specifies the type of relocation entries in the dt jmprel 

IcIUGcUIUM IdUlc. I lllo cllliy o 1 Id 1 1 IIUIU lllc VcllUc L) 1 KrjJ_i/\. 1 lllo clluy 

must accompany a dt jmprel entry. 


DT_JMPREL 


This entry holds the address of the relocation table for the Procedure 
Linkage Table. This relocation table only holds relocation entries for the 
Procedure Linkage Table. All other relocation entries are contained in 
the relocation table addressed by dt rela. The relocation entries in 
this relocation table have a one-to-one correspondence with the 
Procedure Linkage Table entries. See § 11 .6, "Procedure Linkage 
Table (PLT)", on page 137 for further details. 


System V ABI Note: The System V Application Binary Interface, 
PowerPC Processor Supplement specifies that the table of 
dt jmprel relocation entries is wholly contained within the 
relocation table referenced by dt rela. This ABI specifies that 
the dt jmprel table is a separate table from the dt rela table. 
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Table 9-25: Dynamic Array Tag Descriptions (Continued) 



Name 


Meaning 


DT_PPC_GOT 


This entry holds the address of the Global Offset Table, i.e. the address 

of the . got section. This is not the same at the address of the symbol 
global offset table since negative offsets from 
global offset table are allowed. For additional information on 

the Global Offset Table, see § 11 .5, "Global Offset Table (GOT)", on 

page 135. 


DT_PPC_GOTSZ 


This entry holds the total size, in bytes, of the Global Offset Table, i.e. 
the size of the . got section. This entry must accompany a 
dt_ppc_got entry. 


DT_PPC_PLTSZ 


This entry holds the total size, in bytes, of the Procedure Linkage Table, 
i.e. the size of the . pit section. This entry must accompany a 
dt ppc plt entry. 
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9.2 DWARF 

This section defines the information necessary to support the Debug With Arbitrary Record 
Format (DWARF) debugging information format on the PowerPC architecture. This ABI does 
not define a debugging information format, but all implementations of DWARF for this ABI 
shall use the definitions in this section. The reader is referred to Tool Interface Standards 
Portable Formats Specification tor general information on the DWARF debugging information 
format. 

9.2.1 DWARF PowerPC Processor-specific Information 

This section documents the DWARF information specific to the PowerPC processor. 
9.2.1.1 Register Numbers 

The following register number mappings are specified for the PowerPC User Instruction Set 
Architecture (UISA) registers. 



Table 9-26: PowerPC UISA Register Mapping 



Name 


Abbreviation 


Number 


General Purpose Registers 


rO - r31 


0-31 


Floating Point Registers 


f 0 - f 31 


32-63 


Condition Register 


CR 


64 


Floating Point Status and Control Register 


FPSCR 


65 


Fixed Point Exception Register 


XER (or SPR1) 


101 


Link Register 


LR (or SPR8) 


108 


Count Register 


CTR (or SPR9) 


109 


Other Special Purpose Registers 


spr/1 


100 + n 



Note: In general, all registers which have a Special Purpose Register (spr) number will 
have a DWARF register number equal to 100 plus the SPR number. 

The following register number mappings are specified for the PowerPC Virtual Environment 
Architecture (VEA) registers. 



Table 9-27: PowerPC VEA Register Mapping 



Name 


Abbreviation 


Number 


Time Base Lower Register (read only) 


TBR 268 


368 


Time Base Upper Register (read only) 


TBR 269 


369 
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The following register number mappings are specified for the PowerPC Operating 
Environment Architecture (OEA) registers. 

Table 9-28: PowerPC OEA Register Mapping 



Name 


Abbreviation 


Number 


Machine State Register 


MSR 


66 


Segment Registers 


SRO - SR15 


70-85 


Other Special Purpose Registers 


SPRH 


100 + n 



Consult the hardware reference manuals, PowerPC Architecture and PowerPC 603 RISC 
Microprocessor User's Manual, for specific Special Purpose Register numbers and uses. 
The presence of Special Purpose Registers will vary among PowerPC implementations. 
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10 Object Library File Format 

This chapter describes the format of object library files. Object library files are searched by 
the static linker to resolve undefined symbols. The ABI defines two object library file formats. 
The Library File format is the preferred file format. 
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10.1 Archive File Format 

This file format is the same as the Archive File format (AR) used in UNIX System V. See 
System V Application Binary Interface, Chapter 7, for details on the Archive File format. 
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10.2 Library File Format 

The Library File format (LIB) is a modification of the AR file format. A LIB file contains only 
ELF object files. 

10.2.1 LIB File Layout 

A LIB file has the following layout in the indicated order. 

Figure 10-1: LIB File Layout 



LIB file header. 

An optional special member: symbol table (created only if at least one member 
defines non-local symbols.) 

An optional special member: long file name string table (created only if at least one 
member's file name exceeds 15 bytes in length.) 

An optional special member: full file name string table. 

ELF Object File members. 



10.2.2 LIB Header 

A LIB file begins with a LIB file header. All information in the header is viewable ASCII. All 
fields have their values stored in ASCII representation and are left-justified and padded on 
the right with spaces. 



Figure 10-2: LIB File Header, Lib32_File 



#define LIBMAG "!<mlib>\n" 

typedef struct 
{ 

unsigned char lib magic [8] ; 
unsigned char lib class [4] ; 
unsigned char lib data [4] ; 
} Lib32_File; 


Field 


Description 


lib magic 


The field identifies the file as a LIB file and contains the 
sequence of characters in libmag. 

Note: The sequence of characters is not null-terminated. 


lib class 


This field holds the ASCII decimal representation of the class 
of ELF object files in the LIB file. All members of the LIB file 
shall be of the same class. See the e ident [ei class] 
member of the ELF Header for possible values. 
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Figure 10-2: LIB File Header, Lib32_File (Continued) 



lib data 



This field holds the ASCII decimal representation of the data 
encoding of ELF object files in the LIB file. All members of the 
LIB file shall have the same data encoding. See the 
e_ident [ei_data] member of the ELF Header for possible 
values. 



Note: For this ABI, the value of lib_class shall be elfclass32 and the value of 

lib_data shall be ELFDATA2LSB. 
10.2.3 LIB Members 

A LIB file member consists of a member header followed by the unchanged contents of the 
member's file. All member headers begin on a halfword boundary. A newline character ('\n') 
is used if necessary to pad between members. There is no provision for empty areas in the 
LIB file. 



All information in a member header is viewable ASCII. All fields have their values stored in 
ASCII representation and are left-justified and padded on the right with spaces. 

Figure 10-3: LIB Member Header, Lib32_Hdr 



#define LIBFMAG 

typedef struct 
{ 

unsigned char 
unsigned char 
unsigned char 
unsigned char 
unsigned char 
unsigned char 
unsigned char 
} Lib3 2_Hdr; 



™ \ n » 



\n'' 



lib_name [16] 
lib_date [12] 
lib_uid [6] ; 
lib_gid [6] ; 
lib_mode [8] ; 
lib_size [10] 
lib_fmag [2] ; 



Field 



Description 



lib name 



This field contains the member's file name. If the member's file 
name is 15 bytes or less in length, it is stored in this field, 
terminated with a slash ('/') and padded with spaces on the 
right (e.g. "filename . o/ "). If the member's file name 
exceeds 15 bytes in length, the field contains a slash followed 
by the ASCII decimal representation of the name's offset in the 
long file name string table, padded with spaces on the right 
(e.g. "/125 "). 



lib date 



This field contains the ASCII decimal representation of the 
number of seconds since 00:00:00 Universal Time, January 1 , 
1 970. For file members, this is the value of the last 
modification date of the file at the time of its insertion into the 
library. For special members, the value is zero. 
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Figure 10-3: LIB Member Header, Lib32_Hdr (Continued) 



lib uid 


This field contains the ASCII decimal representation of the 
user identifier of the member file at the time of its insertion into 
the library. For special members, the value is zero. 

Note: The value is zero if the file system does not support 
user identifiers. 


lib gid 


This field contains the ASCII decimal representation of the 
group identifier of the member file at the time of its insertion 
into the library. For special members, the value is zero. 

Note: The value is zero if the file system does not support 
group identifiers. 


lib mode 


This field contains the ASCII octal representation of the 
member's file access mode at the time of its insertion into the 
library. For special members, the value is zero. 

Note: The value is zero if the file system does not support 
access modes. 


lib size 


This field contains the ASCII decimal representation of the 
member's size in bytes, exclusive of padding. The member's 
contents begin immediately following the member header. For 
special members, the value is the size of the special members 
data. 


lib fmag 


The field contains the sequence of characters in libfmag. 
Note: The sequences of characters is not null-terminated. 



The member's unchanged contents immediately follow the member header. 



10.2.4 LIB Special Members 

There are three optional special members in a LIB file. If present, they precede all "normal" 
members in the LIB file and are encountered in the following order. 

10.2.4.1 Symbol Table Member 

If at least one member of the LIB defines non-local symbols [i.e. weak and/or global), the LIB 
file's first member will be a symbol table member. This member has a special name 
consisting of a slash followed by spaces ("/ "). 
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The data for this member is partitioned as described below. All words in the symbol table are 
4 bytes in length and use the data encoding indicated in the lib_data member of the file 
header. 



Table 10-1 : Symbol Table Layout 





Size 


Description 


Symbol 
count 


One word. 


This word contains the number (n) of symbols in the 
symbol table. 


File offset 
array 


N words 


Each word in the array is an offset, relative to the 
beginning of the file, to a member of the LIB file. There is a 
one-to-one correspondence between symbol names in the 
string table below and entries in this array. The entries in 
this array provide the offset of the member defining the 
corresponding symbol. 


Symbol 

inTormaiion 

array 


n bytes 


Each byte in the array contains the symbol's type and 
binding information. It is the equivalent to the st info 
information found in ELF symbol tables. There is a one-to- 
one correspondence between symbol names in the string 
table below and entries in this array. The entries in this 
array provide the symbol's type and binding information for 
the corresponding symbol. 


String table 


lib size 
- 5*(N) - 4 


This table consists of a sequence of n null-terminated 
symbol names. Entries in the string table parallel the order 
of members in the LIB file. Thus if two or more members 
define symbols with the same name (which is allowed), the 
string table entries for the symbols will appear in the same 
order as their corresponding members in the LIB file. 



The following example symbol table contains 4 symbols and is 50 bytes in length. The LIB 
file member at offset 0x114 defines name, symbol information stb_weak, stt_func, and 
object, symbol information stb_global, stt_object. The LIB file member at offset 
0x426 defines function, symbol information stb_global, stt_func, and name, symbol 
information stb_global, stt_func. 

Figure 10-4: Symbol Table Example 



Offset 
0 
4 
8 
12 
16 



+ 0 



+ 1 



+ 2 



+ 3 



0x114 



0x114 



0x426 



0x426 



4 entries in the symbol table 
offset of member defining name 
offset of member defining obj ect 
offset of member defining function 
offset of member defining name 
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Figure 10-4: Symbol Table Example (Continued) 

symbol information 



20 


0x22 


0x11 


0x12 


0x12 


24 


n 


a 


m 


e 


28 


\o 


o 


b 


j 


32 


e 


c 


t 


\o 


36 


f 


u 


n 


c 


40 


t 


i 


o 


n 


44 


\o 


n 


a 


m 


48 


e 


\o 







start of the string table 



10.2.4.2 Long File Name String Table Member 

If at least one member's file name exceeds 15 bytes in length, a long file name string table 
member will be present. It follows the symbol table member. This member has a special 
name consisting of two slashes followed by spaces ("// ")■ 



The data for this member is a sequence of file names, each terminated by a two character 
sequence of slash and newline ("An"). The first byte of the data is offset zero in the long file 
name string table. The following example shows lib_name values for various file names. 



Figure 10-5: Long File Name String Table Example 



Member Name 


lib name 


Comment 


regularname . o 


regularname . o/ 


Not in string table 


f ullbigf ilename . o 


/o 


Offset 0 in string table 


evenbiggerf ilename . obj 


/19 


Offset 19 in string table 



Offset 


+ 0 


+ 1 


+ 2 


+ 3 


+ 4 


+ 5 


+ 6 


+ 7 


+ 8 


+ 9 


0 


f 


u 


1 


1 


b 


i 


g 


f 


i 


1 


10 


e 


n 


a 


m 


e 




o 


/ 


\n 


e 


20 


V 


e 


n 


b 


i 


g 


g 


e 


r 


f 


30 


i 


1 


e 


n 


a 


m 


e 




o 


b 


40 


j 


/ 


\n 

















10.2.4.3 Full File Name String Table Member 

An optional special member may exist which contains the full file names for each member in 
the LIB file. It follows the symbol table member and the long file name string table member. 
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This member has a special name consisting of three slashes padded on the right by spaces 

("/// ")■ 

The data for this member is a sequence of null-terminated full file names. There is a one-to- 
one correspondence between entries in the full file name string table and members in the LIB 
file. If the full file name is not available, then the file name (same as lib_name) is used. 

Following is an example of a full file name string table. 

Figure 10-6: Full File Name String Table Example 



Offset 


+ 0 


+ 1 


+ 2 


+ 3 


+ 4 


+ 5 


+ 6 


+ 7 


+ 8 


+ 9 


0 


/ 


s 


r 


c 


/ 


t 


e 


s 


t 


/ 


10 


r 


e 


g 


u 


1 


a 


r 


n 


a 


m 


20 


e 




o 


\o 


/ 


d 


e 


b 


u 


g 


30 


/ 


f 


u 


1 


1 


b 


i 


g 


f 


i 


40 


1 


e 


n 


a 


m 


e 




o 


\o 


e 


50 


V 


e 


n 


b 


i 


g 


g 


e 


r 


f 


60 


i 


1 


e 


n 


a 


m 


e 




o 


b 


70 


j 


\o 
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11 Process Creation and Dynamic Loading 

This chapter contains information about process creation and the initial runtime environment 
for a newly created process. It also contains information on the Global Offset Table and the 
Procedure Linkage Table and how they are initialized at process creation. 
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11.1 Process Virtual Address Space 

The 4 GB virtual address space of a process is partitioned into four areas. 



Table 11-1 : Virtual Address Space Layout 



Start Address 


Area Name 


0x00000000 


Private Memory Area 


(See below) 


Coerced Memory Area 


(See below) 


Global Memory Area 


Oxf 0000000 


System Reserved Area 




Area Name 


Description 


Private Memory 
Area 


This area contains the process' private memory. It contains virtual 
addresses from 0 up to the start of the Coerced Memory Area. 


Coerced Memory 
Area 


This memory area is used for memory objects that are coerced to the 
same virtual address for all process. When a memory object is 
allocated in this memory area, the virtual address range of the object 
is reserved in the virtual address space of every process. However, 
the memory objects in this area must be explicitly mapped into a 
process in order to be visible by that process. A memory object can 
be shared by mapping it into multiple processes. Memory objects in 
this area can have different access protections for each process 
mapping the object. 

The size of the Coerced Memory Area is configurable and is set at 
boot time. 


Global Memory 
Area 


This memory area is used for global memory objects that are coerced 
to the same virtual address for all process. When a memory object is 
allocated in this memory area, the virtual address range of the object 
is reserved in the virtual address space of every process. The object 
is immediately visible in all processes, no explicit mapping is 
necessary. Thus memory objects in the Global Memory Area are 
shared with all processes. All processes have the same access 
protection to the memory object. 

The size of the Global Memory Area is configurable and is set at boot 
time. 


System Reserved 
Area 


This memory area is reserved for use by the system. It is 256 MB in 
size and occupies the virtual address range Oxf ooooooo to 
Oxf f f f f f f f . This area is not addressable by the process. 
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When an executable or dynamic link library is loaded into a process, the various pt_load 
segments are allocated to specific memory areas. All segments are coerced to the same 
virtual address in each process that contains the segment image. 



Table 11-2: Load Module Memory Area Usage 



pt load Segment 


Executable 


Dynamic Link Library 


PF_R PF_X 

(includes Code, GOT, 
PLT and read-only data) 


Private Memory Area 
This is shared with other 
processes running the same 
executable. 


Global Memory Area 
This is shared with all 
processes. 


PF_R PF_W 

(read/write data) 


Private Memory Area 

This is not shared with other 

processes but each process' 

copy resides at the same virtual 

address. 


Coerced Memory Area 
This is not shared with 
other processes but each 
process' copy resides at the 
same virtual address. 


PF_R | PF_W | PF_S 

(shared read/write data) 


Private Memory Area 
This is shared with other 
processes running the same 
executable. 


Coerced Memory Area 
This is shared with all other 
processes using the 
dynamic link library. 



In order to efficiently support demand paging from load modules, the load modules must be 
statically linked with the file offsets and virtual addresses of segments congruent modulo the 
page size. Although the current page size for PowerPC is 4096 bytes, file offsets, 
p_of f set, and virtual addresses, p_vaddr, of segments shall be congruent modulo 64K 
(oxioooo) or larger powers of 2. This allows files to be suitable for paging if/when 
implementations with larger page sizes appear. The value of the p_align member of each 
program header entry shall be Oxioooo. 
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Following is an example of an executable file that has been linked with a base address of 
Oxoooioooo (64K) 



Figure 11-1: Example Executable File 



File Offset 


ELF File 


Virtual 
Audi ess 


0x0 


r— 1 r— 1 |___|_„ 

ELF Header 






Program Header table 






Other Information 




0x2f 8 


Text Segment 


0x000102f 8 




0xi3dc8 bytes 


0x000242f f 


0xl40c0 


Data Segment 


0x000340c0 




0xia58 bytes 


0x000390f f 


0xl5bl8 


Other Information 











Table 11-3: Example Executable Program Header Table Entries 



Member 


Text Segment 


Data Segment 


p_type 


PT_LOAD 


PT_LOAD 


p offset 


0x2f 8 


0xl40c0 


p vaddr 


0x000102f 8 


0x000340c0 


p paddr 


o (unspecified) 


o (unspecified) 


p filesz 


0xl3dc8 


0xla58 


p memsz 


0x14008 


0x5040 


p flags 


PF_R PF_X 


PF_R PF_W 


p align 


0x10000 


0x10000 



Even though the file offsets and the virtual addresses of the load segments are congruent 
modulo 64K, up to four pages in the ELF file can hold impure text or data. 

• The first page of the text segment may contain the ELF header and other non-text 
information. 

• The last page of the text segment may contain a copy of the beginning of the data 
segment. 

• The first page of the data segment may contain a copy of the end of the text segment. 
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• The last page of the data segment may contain non-data information. 

Logically, the system enforces memory access permissions as if each load segment were 
complete and separate in the ELF file. Segment addresses are adjusted to ensure that each 
logical page in the virtual address space has a single set of memory access permissions. 

In Figure 11-1, "Example Executable File", above, the file page spanning the end of the text 
segment and the beginning of the data segment, file offset 0x14000 to 0x15000, is mapped 
into memory twice. First at virtual address 0x24 ooo for the text segment and second at 
virtual address 0x34000 for the data segment. 

If the data segment has p_memsz greater than p_f ilesz, then the memory between 
p_f ilesz and p_memsz holds uninitialized data which is defined by the system to begin 
with zero values. Thus the memory in this range must be set to zero by the loader. 

Figure 11-2: Example Executable Process Image Segments 



Virtual Address 


0x00010000 


Header padding 






0x2 f 8 bytes 




0x000102f 8 


Text Segment 






0xi3dc8 bytes 




0x000240c0 


Data padding 






0xf4 0 bytes 








0x00034000 


Text padding 






Oxco bytes 




0x000340c0 


Data Segment 






0xia58 bytes 




0x00035bl8 


Uninitialized data 






(cleared to zeros) 






0x3 5e8 bytes 




0x00039100 


Page padding 






Oxf oo bytes 









The relative position of segments in a load module, as specified by the virtual addresses in 
the program header table, need not be maintained by the loader. The loader can locate the 
segments of a load module at any virtual address without regard to its relative relationship 
with the other segments in the load module. This is possible for the following reasons. 

• All load modules, both executables and dynamic link libraries, contain position 
independent code. 
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• The GOT and PLT are located in the text segment and there is only one text segment 
per load module. All references between the code and the GOT and PLT are 
intrasegment and thus invariant. 

• All intersegment references among data segments shall have a relocations (preferably 
r_ppc_relative) to adjust them for changes in the relative positions of the segments. 
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11.2 Process Initialization 

This section contains information the initialization of a process. An process consists of an 
executable and multiple dynamic link libraries dynamically linked together into the process 
memory image. 

An OS/2 dynamic link library is a dynamic link library with an os_type of eos_os2. A 
Shared Services dynamic link library is a dynamic link library with an os_type of eos_pn. 

11.2.1 OS/2 Process 

The entry point of an OS/2 executable is specified by the e_entry member of the ELF 
header. When control is passed to the entry point, all OS/2 dynamic link libraries in the 
process have been called for initialization. Any Shared Services dynamic link libraries used 
by the process must be explicitly called for initialization, if necessary. The contents of the 
registers at the entry point are as follows. 



Table 11-4: OS/2 Process Initial Register State 



Register 


Contents 


rl 


Stack pointer. 


r2 


Pointer to current thread's Thread Information Block. See § 11 .4, "Thread 
Information Block", on page 134. 


r3 


Module handle for the executable. 


r4 


0 (zero). 


r5 


Pointer to the process' environment data. The environment data is a 
sequence of null-terminated strings followed by a null byte. 


r6 


Pointer to the command line. The command line is a null-terminated string. 


LR 


Return address to the system. 


All other 
registers 


Contents are unspecified. 



11.2.1.1 Dynamic Linking of Shared Services Dynamic Link Libraries 

Shared Services dynamic link libraries may be dynamically linked into the address space of 
an OS/2 process. The converse is not true. 
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11.2.2 Shared Services Process 

The entry point of a Shared Services executable is specified by the e_entry member of the 
ELF header. Dynamic link libraries in the process must be explicitly called for initialization, if 
necessary. The contents of the registers at the entry point are as follows. 



Table 11-5: Shared Services Process Initial Register State 



Register 


Contents 


rl 


Stack pointer. 


r2 


Pointer to current thread's Thread Information Block. See § 11 .4, "Thread 
Information Block", on page 134. 


r3 


Pointer to the argument information. The argument information consists of 
argc followed by the argv array followed by the env array. 


All other 
registers 


Contents are unspecified. 



11.2.3 OS/2 Dynamic Link Library Initialization 

The initialization/termination entry point of an OS/2 dynamic link library is specified by the 
dt_initterm entry in the Dynamic Segment. The default value for dt_initterm is the 
address of the symbol _DLL_initTerm. An OS/2 dynamic link library may be called at the 
initialization/termination entry point when it is made part of the process image. This is 
determined by the dt_it value. The default value of dt_it is 

elf32_it_info(it_global, it_global). Shared Services dynamic link libraries must 
be explicitly called for initialization, if necessary. The contents of the registers upon entry to 
the initialization/termination entry point are as follows. 



Table 11-6: Dynamic Link Library Initialization Register State 



Register 


Contents 


rl 


Stack pointer. 


r2 


Pointer to current thread's Thread Information Block. See § 11 .4, "Thread 
Information Block", on page 134. 


r3 


Module handle for the dynamic link library. 


r4 


0 (zero) indicating the initialization/termination entry point is being called for 
initialization. 


LR 


Return address to the system. 


All other 
registers 


Contents are unspecified. 
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11.3 Process Termination 

This section contains information the termination of a process. When a process is 
terminated, all OS/2 dynamic link libraries that are part of the process image may get called 
for termination. Shared Services dynamic link libraries must be explicitly called for 
termination, if necessary. 

11.3.1 OS/2 Dynamic Link Library Termination 

The initialization/termination entry point of an OS/2 dynamic link library is specified by the 
dt_initterm entry in the Dynamic Segment. An OS/2 dynamic link library may be called at 
the initialization/termination entry point when it is removed from the process image. This is 
determined by the dt_it value. Shared Services dynamic link libraries must be explicitly 
called for termination, if necessary. The contents of the registers upon entry to the 
initialization/termination entry point are as follows. 



Table 11-7: OS/2 Dynamic Link Library Termination Register State 



Register 


Contents 


rl 


Stack pointer. 


r2 


Pointer to current thread's Thread Information Block. See § 11 .4, "Thread 
Information Block", on page 134. 


r3 


Module handle for the dynamic link library. 


r4 


1 (one) indicating the initialization/termination entry point is being called for 
termination. 


LR 


Return address to the system. 


All other 
registers 


Contents are unspecified. 
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11.4 Thread Information Block 

The r2 register always points to the current thread's Thread Information Block. The r2 
register should never be modified by the application. 

Figure 11-3: Thread Information Block, thread inf o block t 



typedef struct 
{ 

void * exception 
void * stacklow; 
void * stackhigh 
void * extended; 
uint32 version; 
uint32 threadid; 
void * syncl; 
void * sync2 ; 
uint32 reservedl 
uint32 reserved2 
} thread info block t 




Member 


Description 


exception 


This member holds the head of the thread's exception handler 
chain. 


stacklow 


This member holds the lowest valid address in the thread's 
stack. 


stackhigh 


This member holds the next address greater than the highest 
valid address in the thread's stack. 


extended 


The member holds the address of the thread's extended 
thread information block. The extended thread information 
block will contain thread package-specific information. 


version 


This member holds the version number of the 

thread_inf o_block_t data structure. 


threadid 


This member holds the thread's id. The thread id is unique 
within the process. 


syncl 
sync 2 


These members are reserved for synchronization. 


reservedl 
reserved2 


These members are reserved for future use. 



Note: uint32 is an unsigned 32-bit integer data type. 

See the OS/2 Programming documentation for a description of the extended thread 
information block for OS/2 processes. 
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11 .5 Global Offset Table (GOT) 

In general, position independent code cannot contain absolute virtual addresses. A load 
module uses its Global Offset Table to hold the absolute virtual addresses that cannot be 
held in the code. Using position independent techniques, the code obtains the addresses of 
memory objects from the GOT and can then access the objects. 

The Global Offset Table is initialized, by the static linker, to contain the information needed by 
its relocation entries (See § 9.1 .2.3, "Relocation", on page 106 for additional information on 
relocation types). Entries in the GOT are relocated only if they have associated relocation 
entries, some of which are r_ppc_relative and r_ppc_glob_dat. The dynamic linker 
processes the relocation entries and sets the GOT entries to the resultant values. 

Each load module has its own Global Offset Table and consequently a symbol may appear in 
several tables. The dynamic linker processes all Global Offset Table relocations for all load 
modules before transferring control to the process. This ensures that all absolute virtual 
addresses are valid and available for the process code. Once a process begins execution its 
memory segments must remain at fixed virtual addresses. The Global Offset Table resides in 
the .got section referenced by the dt_got entry in the Dynamic segment 

The symbol _global_offset_table_ is used to access the Global Offset Table and is the 
reference address for the GOT. The symbol may reside in the center of the GOT allowing for 
both positive and negative offsets into the array of GOT entries. Four entries in the Global 
Offset Table are reserved. 



Table 11-8: Reserved Global Offset Table Entries 



Entry 


Description 


_GLOBAL_OFFSET_TABLE_ [ - 1] 


This entry shall hold a blrl instruction. To obtains the 
address of the Global Offset Table, a function can call 
this entry (bl _global_offset_table_-4) and 
have the address of the symbol 

_global_offset_table_ returned in LR. 


_GLOBAL_OFFSET_TABLE_ [0] 


This entry shall hold the address of the Dynamic 
Segment, referenced by the symbol dynamic. This 
entry is initialized by the static linker. 


_GLOBAL_OFFSET_TABLE_ [1] 


Reserved and shall be set to zero. 


_GLOBAL_OFFSET_TABLE_ [2] 


Reserved and shall be set to zero. 



A load module's Global Offset Table must reside at a fixed relative location to the load 
module's code. The code establishes addressability to the GOT by performing a branch and 
link to _global_offset_table_-4 which returns the address of 
_global_offset_table_ in lr. Because the branch and link instruction must be 
constructed by the static linker, a fixed relative relationship exists between the code and 
Global Offset Table. This can be satisfied by the static linker placing the GOT in the same 
segment as the code, a read-only segment, or by placing the GOT in some other segment 
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and having the system loader respect the relative placement of segments as specified in the 
load module by the static linker. 

Note: The use of the branch and link instruction to establish addressability to the GOT 
requires that the label _global_offset_table_ is within ±32MB of the 
bl _global_offset_table_-4 instruction in all functions accessing the GOT. 



Reviewer's Note: Alternate schemes of establishing addressability to the GOT have been 
proposed. In essence, instead of bl _global_offset_table_-4 to establish 
addressability to the GOT, a bl to a find_got routine that is at a fixed relative location 
to the code is used. The find_got routine is patched by the loader to return the 
address of the GOT, which could now be placed anywhere (most interesting is shared, 
coerced memory). This scheme could be used in addition to the current scheme. See 
the example below. 



Description 


Code Sequence 


Current ABI 


bl _GLOBAL_OFFSET_TABLE_- 4 
blrl 

_GLOBAL_OFFSET_TABLE_ : 
mflr %r32 


Additional technique for 
establishing GOT 
addressability. The 
compiler would call an 
alternate function to return 
the address in ri2. This 
function would be patched 
by the loader to return the 
correct address of the GOT. 


bl _GLOBAL_OFFSET_TABLE_ADDRESS 

_GLOBAL_OFFSET_TABLE_ADDRESS : 

addis %rl2, 0, _GLOBAL_OFFSET_TABLE_@ha 
addi %rl2, %rl2, _GLOBAL_OFFSET_TABLE_@l 
blr 

mr %r31, %rl2 
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11.6 Procedure Linkage Table (PLT) 

The Procedure Linkage Table redirects function calls to functions whose location is unknown 
by the static linker. The static linker cannot resolve execution transfer between load modules 
and uses the PLT as an intermediary. The static linker arranges for control to be transferred 
to a PLT entry which will be modified by the dynamic linker to transfer control to the proper 
destination. This preserves the position independence of the code and allows load modules 
to reside at arbitrary memory locations. Each load module has its own Procedure Linkage 
Table to direct calls to functions external to the load module. The Procedure Linkage Table 
resides in the .pit section referenced by the dt_ppc_plt entry in the Dynamic Segment. 

For this ABI, the Procedure Linkage Table is not initialized in the load module by the static 
linker. Instead, the static linker simply reserves space for the PLT in the load module and the 
dynamic linker initializes and manages its memory image. The exact contents of the PLT are 
implementation dependent subject to the following rules. 

1 . The Procedure Linkage Table is partitioned in the following manner with n being the 
number of PLT entries in the load module. 



PLT Prologue 

1 8 words (72 bytes) 

PLT Entries 

N * 2 words (n * 8 bytes) 

PLT Epilogue 

N words (n * 4 bytes) 



2. The PLT Prologue is reserved for use by the dynamic linker. There shall be no 
branches from the load module into the Prologue. 

3. For each function call in the load module redirected through the PLT, there shall be 
one PLT entry, 2 words in length. The static linker shall direct all branches for 
redirected function calls to the first word of its corresponding PLT entry, e.g. for PLT 
entry i, i ranging from 1 to N inclusive, the branch would be directed to .pit + 72 + 
(i-1)*8. 

If n > 81 92, then for PLT entry indices i, where i > 81 92, only even indices will be 
used and the corresponding PLT entries shall be 4 words in length. 

4. The PLT Epilogue is reserved by use by the dynamic linker. There shall be no 
branches from the load module into the Epilogue. 

Note: The use of branch and link instructions to transfer control to PLT entries requires that 
the PLT entries are within +32MB of the bl instructions. 

The relocation entries located via the dt_jmprel tag in the Dynamic segment provide the 
information necessary for the dynamic linker to setup the Procedure Linkage Table. There is 
a one-to-one correspondence between the PLT entries and the dt_jmprel relocation 
entries, i.e. the first relocation entry provides the relocation information for the first PLT entry 
and so on. Each relocation entry is of type r_ppc_jmp_slot and the r_of f set member 
holds the location of the first byte of the associated PLT entry, e.g. .pit + 72 + (i - 1) * 8. 
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Following is an example used to illustrate how the Procedure Linkage Table might be utilized 
by a dynamic linker. This is an example only and does not specify the contents of the PLT or 
the behavior of the dynamic linker. Figure 11-4, "Procedure Linkage Table Example", shows 
how the dynamic linker might initialize the PLT for an OS/2 load module. 



Figure 11-4: Procedure Linkage Table Example 



# PLT Prologue (18 words) 


. PLTcall : 




addis 


%rll, %rll, .PLTtableOha 


lwz 


%rll, . PLTtabletal (%rll) 


mtctr 


%rll 


bctr 




nop 




nop 




nop 




nop 




nop 




nop 




nop 




nop 




nop 




nop 




nop 




nop 




nop 




nop 




# PLT Entries (2 * N words) 


. PLT1 : 




addi 


%rll, 0, 4*0 


b 


. PLTcall 


. PLT j : 




addi 


%rll, 0, 4*(j - 1) 


b 


. PLTcall 


. PLTJf : 




b 


<target> 


nop 




. PLTN: 




addi 


%rll, 0 , 4* (N - 1) 


b 


. PLTcall 


# PLT Epilogue (N words) 


. PLTtable : 




<N word table > 
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Process Creation and Dynamic Loading 
The PLT is initialized by the dynamic linker during process initialization. 

1 . The dynamic linker writes the instructions for . PLTcall in the PLT Prologue adjusting 
them for the virtual address of . PLTtable. 

2. The dynamic linker locates the PLT relocation entry for each PLT entry i. The relocation 
entry will be of type r_ppc_jump_slot, its r_of f set member will contain the address 
of . PLTi and its symbol table index will point to the target symbol, e.g. f oo. 

3. The dynamic linker determines the proper value of symbol f oo and initializes the code at 
. PLTi in one of two ways. 

• If f oo is reachable from . PLTi by a single branch instruction, a branch to f oo 
instruction is placed in the first word at . PLTi. 

• If f oo is not reachable from . PLTi by a single branch instruction, the address of 
f oo is stored in the PLT Epilogue at . PLTtable + (i - 1) * 4, an instruction which 
loads rii with (i - 1 ) * 4 is placed in the first word at . PLTi and a branch to 

. PLTcall instruction is placed in the second word at . PLTi. 

If i > 81 92, then i must be even and the size of . PLTi is 4 words. More than one 
instruction will be necessary to load rii with (i - 1) * 4. 

4. The PLT entry is now initialized to transfer control to the target function either directly, via 
a direct branch, or indirectly through . PLTcall. 

Note: Lazy binding of PLT entries is not supported by this ABI. 
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Appendix A Compiler Support Extensions 

This appendix contains ABI extensions added to support additional compiler function. 

This appendix also includes the description of the recently adopted COMDAT extension to 
ELF. 
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A.1 ELF 

A. 1.1 Sections 

The following section types are defined. These sections are used to communicate 
information from the compiler to the static linker. These sections are only valid in object files. 



Table A-1 : Section Types, sh type 



Name 


Value 


Meaning 


SHT_COMDAT 


12 


This section contains COMDAT code or data and is 
otherwise treated the same as sht progbits. The 
static linker will choose only one sht comdat 
section of a given name from all like named 
sht comdat sections encountered during the link. 


SHT_IDMDLL 


0x60001002 


This section holds the information to perform symbol 
name demangling. See § A.1 .1 .2, "Symbol Name 
Demangling", on page 144 for details. 


SHT_DEFLIB 


0x60001003 


This section holds the information about static 
libraries to be processed by the static linker. See 
§ A.1 .1 .3, "Default Library", on page 1 45 for details. 



Two members in the section header, sh_link and sh_inf o, hold special information 
depending on the section type. 



Table A-2: sh link and sh inf o Interpretation 



sh type 


sh link 


sh info 


SHT_COMDAT 


The section header index of 
the section into which this 
section shall be combined in 
the output file. This will allow 
many small sections to be 
combined into one. The 
value shn undef indicates 
that this section is not to be 
combined into another 
section. 


COMDAT selection criteria. 
See Table A-3, "COMDAT 
Selection Criteria" below for 
possible values. 
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Table A-2: sh link and sh inf o Interpretation (Continued) 



sh type 


sh link 


sh info 


SHT_PROGBITS 


The section header index of 

tho cQftinn into \A/hi/~ , h thic 
Lilt? ocOUUII II1LU VVIIIOII LI lib 

section shall be combined in 
the output file. This will allow 
many small sections to be 
combined into one. The 
value shn undef indicates 
that this section is not to be 
combined into another 
section. 


0 


SHT_IDMDLL 
SHT_DEFLIB 


The section header index of 
the string table used by 
entries in this section. 


0 



The sht_idmdll and sht_deflib sections must be word aligned. Thus the 
sh_addralign value for these sections is 4. 



A.1.1.1 COMDAT Section 

Object files may contain one or more sht_comdat sections uniquely named within the 
object file. These section exist to support C++ templates and other like constructs. A 
compiler can emit the same sht_comdat section into several object files using the same 
section name. The static linker will select one of the like named sections to be placed in the 
resulting load module. The selection is based upon the following criteria specified in the 
sh_inf o field of the section header table entry of the COMDAT section. 



Table A-3: COMDAT Selection Criteria 



Name 


Value 


Meaning 


COMDAT_NONE 


0 


Invalid selection criteria. 


COMD AT_NOMAT CH 


i 


Only one instance of a sht comdat section of the 
given name is allowed. A link warning is generated 
otherwise. 


COMD AT_P I C KANY 


2 


Pick any instance of a sht comdat section of the 
given name. 


COMDAT_SAMESIZE 


3 


Pick any instance of a sht comdat section of the 
given name but all instances of sht comdat 
sections of the given name must have the same size. 
A link warning is generated otherwise. 
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The following symbol bindings are also defined. 



Table A-4: Symbol Binding, elf32_st_bind 



Name 


Value 


Meaning 


STB_GLOBALOMIT 


3 


A global symbol that may be omitted from the output file. If 
the symbol is undefined and there are no references to the 
symbol (no relocation entries specifying its index), then the 
symbol need not be defined (nor is it searched for in 
libraries). It is otherwise treated the same as 

STB_GLOBAL. 



A. 1.1. 2 Symbol Name Demangling 

Each object file may contain one sht_idmdll section. The section contains exactly one 

Elf 32_Demangle Structure. 

Figure A-1: Demangle Information Structure, Elf 32_Demangle 



typedef struct 
{ 

Elf 32 Word idm dllname; 
Elf 32 Word idm initparms; 
} Elf 32 Demangle; 


Member 


Description 


idm dllname 


This member identifies the string table index of the name of 
the dynamic link library containing the symbol name 
demangling function. The name string is UTF-8 encoded. 


idm initparms 


This member holds the string table index of the parameters to 
the dynamic link library initialization function. 



The very first section of this type encountered by the linker will define the demangle dynamic 
link library used by the static linker. The demangle dynamic link library contains two entry 
points. The Static linker shall call InitDemangleID32 before using the DemangleID32 

function to demangle symbol names. 



Table A-5: initDemangieiD32 Function Prototype 



unsigned long InitDemangleID32 ( unsigned char *pszInitParms ) ; 


Parameter 


Description 


pszInitParms 


This parameter is the null-terminated string provided by the 
idm initparms member of the Elf 32 Demangle Structure. 



144 



Release 1 



Table A-5: initDemangieiD32 Function Prototype (Continued) 



Return Value 


A non-zero return value indicates successful initialization. A 
zero return value indicates that initialization failed. If a failure is 
indicated, the DemangleiD32 function in the dynamic link 
library should not be called. 


Table A-6: DemangleiD32 Function Prototype 


unsigned long DemangleID32 ( unsigned char *pszMangledName, 

unsigned char *pbDemangledName , 
unsigned long ulDemangledName ) ; 


Parameter 


Description 


pszMangledName 


This parameter is the null-terminated symbol name to be 
demangled. 


pbDemangledName 


This parameter is a pointer to a buffer where the null-terminated 
demangled name is to be returned. 


ulDemangledName 


This parameter is the size of the buffer. 


Return Value 


A non-zero return value indicates successful initialization. A 
zero return value indicates that initialization failed. If a failure is 
indicated, the pbDemangledName buffer contents are invalid. 



A. 1.1. 3 Default Library 



Each object file may contain one sht_deflib section. The section contains an array of 
Elf 32_Library structures. Each structure represents a library to be added to the end of 
the list of default libraries to be searched by the static linker to resolve undefined symbols. 



Figure A-2: Default Library Structure, Elf 32_Library 



typedef struct 
{ 

Elf 32_Word 
} Elf32 Library; 






lib name; 


Member 


Description 


lib name 


This member identifies the string table index of the name of a 
static library. The name string is UTF-8 encoded. 



A. 1.2 Note Information 

The following note information is defined. This information, if present, resides in a pt_note 
segment of a load module. 
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A. 1.2.1 Browser Information 

A list of the full file names of the object files that contributed to the load module is kept in the 
browse information. This information can be used by a code browser. 



Table A-7: Browser Information 



Field 


Description 


namesz 


The size of name including the null-terminating byte. 


descsz 


The size of desc information. 


type 


1 


name 


The null-terminated string "ibm". 


desc 


This information is a collection of records described in § A.1 .2.1 .1 , "Browser 
Information Records". 



A.1. 2.1.1 Browser Information Records 

There are three record types. Each record begins with a single byte containing the record 
type. It is immediately followed by a null-terminated string containing a full file name. The full 
file name strings are UTF-8 encoded. 

Table A-8: Browser Information Record Types 



Type 


Description 


0 


The following string is the full file name of an object file included in the load 
module. 


i 


The following string is the full file name of an object library file which has some of 
its member object files included in the load module. This record type is followed by 
additional information describing which member object files are included in the 
load module. If necessary, a padding byte of zero follows the string to align the 
additional information on a halfword boundary. 

The additional information begins with a halfword containing the number, m, of 
member object files included in the load module. This is followed by m halfwords 
each containing the member number of the member object file. (e.g. 1 represents 
the first member object file in the object file library.) 


2 


The following string is the full file name of an object library file which has all of its 
member object files included in the load module. 
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A. 1.2.2 Version Information 

File version information may need to be included in a load module. This information can be 
used for file version identification and product service. 



Table A-9: Version Information 



Field 


Description 


namesz 


The size of name including the null-terminating byte. 


descsz 


The size of desc including the null-terminating byte. 


type 


2 


name 


The null-terminated string "IBM". 


desc 


A null-terminated, UTF-8 encoded version string. 



A. 1.2.3 Description Information 

The static linker may have a descriptive comment from the user to be included in a load 
module. This information can be a description of the load module. 

Table A-10: Description Information 



Field 


Description 


namesz 


The size of name including the null-terminating byte. 


descsz 


The size of desc including the null-terminating byte. 


type 


3 


name 


The null-terminated string "ibm". 


desc 


A null-terminated, UTF-8 encoded description string. 
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End of Document 

This is the last page of the document. 
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